@opsee/cli 0.11.9

package/src/foreman/worker-process.ts

@@ -0,0 +1,488 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import type { Account } from "./account.js";
+import { PROCESS_GROUPS, signalProcessGroup, stopProcessGroup } from "./process-group.js";
+import type { AdapterEvent, TurnFailureReason, TurnHandle, TurnSandbox } from "./worker-adapter.js";
+
+/**
+ * What every vendor Worker Adapter shares below the vendor protocol: the process seam, the
+ * environment that lets the Account alone name the Worker's identity (ADR-0013), and one turn's
+ * lifecycle over a child process, from spawn through line-by-line stdout to the exit that ends the
+ * turn without a result. A vendor adapter supplies the command line, the two variable names its
+ * binary reads, and a `handleMessage` that turns its own stream protocol into adapter events;
+ * everything about pipes, stall timers, kills and exit codes lives here once.
+ */
+
+/** How the process seam sees a running Worker; real processes and fixture replayers both fit. */
+export interface SpawnedProcess {
+  stdout: AsyncIterable<string | Uint8Array>;
+  stderr: AsyncIterable<string | Uint8Array>;
+  /** Resolves when the process ends; rejects when it could not be started at all. */
+  exited: Promise<{ code: number | null; signal: string | null }>;
+  /** Starts stopping the Worker and what it spawned; the exit shows up on `exited`. */
+  kill(): void;
+  /** The OS pid, when there is a real process behind this (the Process Table records it). */
+  pid?: number;
+}
+
+export interface SpawnOptions {
+  cwd: string;
+  env: Record<string, string>;
+}
+
+export type ProcessSpawner = (command: string, args: string[], options: SpawnOptions) => SpawnedProcess;
+
+/** How long a killed Worker gets to leave after SIGTERM before its whole group is SIGKILLed. */
+export const KILL_GRACE_MS = 5_000;
+
+/**
+ * The real seam: a child process with stdin closed and both output streams piped, in its own
+ * process group so that `kill()` reaches the shells the Worker started underneath it (a Codex
+ * `command_execution` runs under `/bin/zsh -lc`; a Claude Code `Bash` tool likewise). `stop()` must
+ * never leave a Worker's children running in the Workspace. `graceMs` is how long the group gets
+ * after SIGTERM; the tests shorten it.
+ */
+export function makeProcessSpawner(graceMs = KILL_GRACE_MS): ProcessSpawner {
+  return (command, args, options) => {
+    const child = nodeSpawn(command, args, { cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"], detached: PROCESS_GROUPS });
+    let done = false;
+    const exited = new Promise<{ code: number | null; signal: string | null }>((resolve, reject) => {
+      child.once("error", (error) => {
+        done = true;
+        reject(error);
+      });
+      child.once("exit", (code, signal) => {
+        done = true;
+        resolve({ code, signal });
+      });
+    });
+    // An unobserved rejection here would crash the process before the adapter reports launch_failed.
+    const settled = exited.catch(() => undefined);
+    let stopping: Promise<void> | undefined;
+    const stop = () => {
+      stopping ??= stopProcessGroup(child, settled, graceMs, () => done);
+      return stopping;
+    };
+    trackLiveProcess({ child, settled, stop });
+    return { stdout: child.stdout!, stderr: child.stderr!, exited, kill: () => void stop(), pid: child.pid };
+  };
+}
+
+export const spawnProcess: ProcessSpawner = makeProcessSpawner();
+
+/** A detached child this process must not leave behind: a Worker, or the app a Verifier round
+ * started (run-recipe.ts `startApp`). */
+export interface LiveProcess {
+  child: ReturnType<typeof nodeSpawn>;
+  /** Resolves once the child has exited; must never reject. */
+  settled: Promise<unknown>;
+  stop: () => Promise<void>;
+}
+
+/**
+ * A detached child outlives a parent that dies, so this process keeps a registry of the Workers
+ * (and the Verifier's apps) it has running and stops them when it goes away itself. This is not
+ * the Process Table (that is the durable, per-machine record the daemon keeps); it is the
+ * in-memory list of what this process spawned and has not yet seen exit. Two hooks, installed
+ * once on the first real spawn:
+ *
+ * - On SIGINT, SIGTERM or SIGHUP: stop every group (SIGTERM, then SIGKILL after the grace period),
+ *   wait for them, then re-raise the signal, so a command without a handler of its own still ends
+ *   the way Node would have ended it, only after its Workers are gone.
+ * - On `exit` (normal completion or `process.exit`): there is no time to be graceful, so anything
+ *   still alive gets SIGKILL outright.
+ */
+const liveWorkers = new Set<LiveProcess>();
+let hooksInstalled = false;
+
+/** Puts a detached child on the registry until it exits; installs the hooks the first time. */
+export function trackLiveProcess(worker: LiveProcess): void {
+  liveWorkers.add(worker);
+  worker.settled.then(() => liveWorkers.delete(worker));
+  if (hooksInstalled) return;
+  hooksInstalled = true;
+  installLiveWorkerHooks(process);
+}
+
+/** How many detached children this process still has on its registry; for tests. */
+export function liveProcessCount(): number {
+  return liveWorkers.size;
+}
+
+/** The subset of `process` the hooks use, so a test can drive them with an emitter of its own. */
+export interface HookableProcess {
+  pid: number;
+  on(event: NodeJS.Signals | "exit", listener: () => void): unknown;
+  listenerCount(event: NodeJS.Signals): number;
+  kill(pid: number, signal: NodeJS.Signals): unknown;
+}
+
+/**
+ * Installs the exit and signal hooks described on `liveWorkers`. Exported for the test only.
+ *
+ * Whether anyone else was listening is read at signal time, before the asynchronous stop: a
+ * daemon's `once` listener has already removed itself by the time the stop finishes, and counting
+ * then would re-raise the signal into the daemon mid-shutdown. The listener stays installed, so a
+ * repeat signal during the grace period does not fall through to Node's default exit (which skips
+ * the `exit` hook and the pending SIGKILL escalation); it SIGKILLs every live group and re-raises
+ * by the same rule.
+ */
+export function installLiveWorkerHooks(proc: HookableProcess): void {
+  proc.on("exit", () => {
+    for (const w of liveWorkers) signalProcessGroup(w.child, "SIGKILL");
+  });
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+    let stopping = false;
+    proc.on(signal, () => {
+      const othersListening = proc.listenerCount(signal) > 1;
+      const reraise = () => {
+        if (!othersListening) proc.kill(proc.pid, signal);
+      };
+      if (stopping) {
+        for (const w of liveWorkers) signalProcessGroup(w.child, "SIGKILL");
+        reraise();
+        return;
+      }
+      stopping = true;
+      Promise.all([...liveWorkers].map((w) => w.stop())).finally(reraise);
+    });
+  }
+}
+
+/**
+ * Variables removed from the inherited environment and from request overrides before the Account's
+ * are set, so that the Account alone decides which identity the Worker runs as: a stray key in the
+ * Foreman's shell must not silently bill a subscription Account, and one vendor's Worker has no
+ * business seeing the other's key. `CLAUDECODE` and `CLAUDE_CODE_ENTRYPOINT` mark a nested run when
+ * the Foreman is itself started from inside Claude Code, which the binary treats differently.
+ * `CODEX_API_KEY` is the variable `codex exec` takes a key from ahead of any stored login and
+ * `CODEX_ACCESS_TOKEN` an agent-identity token (codex-rs/login/src/auth/manager.rs, `load_auth`).
+ */
+export const STRIPPED_ENV = [
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "CLAUDE_CONFIG_DIR",
+  "CLAUDECODE",
+  "CLAUDE_CODE_ENTRYPOINT",
+  "OPENAI_API_KEY",
+  "CODEX_API_KEY",
+  "CODEX_ACCESS_TOKEN",
+  "CODEX_HOME",
+] as const;
+
+/** `source` with every identity variable (`STRIPPED_ENV`) and every unset entry removed: the one
+ * filter both a Worker's environment and a Gate's (core/gates.ts) start from, so a shell the
+ * Foreman starts on a Worker's behalf never inherits a vendor key from the Foreman's own shell. */
+export function withoutIdentityEnv(source: Readonly<Record<string, string | undefined>>): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value !== undefined && !(STRIPPED_ENV as readonly string[]).includes(key)) env[key] = value;
+  }
+  return env;
+}
+
+/**
+ * What a `readonly-browser` turn (the Verifier) is denied on top of `STRIPPED_ENV`: the Foreman's
+ * own Opsee token, the code-host tokens `glab` and `gh` read, and every cloud credential by prefix.
+ * The Verifier's prompt quotes text from the Task and its browser reads pages the implementer
+ * wrote; it needs none of these, and an environment that has none of them is what keeps a
+ * journey that was talked into running a command from finding anything to send. Applied by
+ * `buildWorkerEnv` after the identity filter, so it cannot be overridden through the request.
+ */
+export const VERIFIER_STRIPPED_ENV = ["OPSEE_API_TOKEN", "GITLAB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"] as const;
+export const VERIFIER_STRIPPED_ENV_PREFIXES = ["AWS_", "GOOGLE_", "AZURE_"] as const;
+
+/** `env` less everything `VERIFIER_STRIPPED_ENV` and its prefixes name. */
+export function withoutVerifierEnv(env: Readonly<Record<string, string>>): Record<string, string> {
+  const kept: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if ((VERIFIER_STRIPPED_ENV as readonly string[]).includes(key)) continue;
+    if (VERIFIER_STRIPPED_ENV_PREFIXES.some((prefix) => key.startsWith(prefix))) continue;
+    kept[key] = value;
+  }
+  return kept;
+}
+
+/** Thrown by `buildWorkerEnv` when the Account cannot be launched; the message never carries a value. */
+export class LaunchError extends Error {}
+
+/**
+ * A `LaunchError` the Foreman decided for itself: the Account's credential is not there to hand to
+ * the vendor at all (OPS-288). Separate from its parent because the two want different answers —
+ * a missing binary is worth another attempt, a key variable that is not set is not, and the Account
+ * it names is quarantined rather than retried.
+ *
+ * This is the one credential failure with no false positive in it. Every other one is a guess about
+ * a vendor's prose; this one is a fact the adapter established before spawning anything, which is
+ * why it needs no repeat before it counts (`CREDENTIAL_FAILURES_BEFORE_QUARANTINE`).
+ */
+export class CredentialError extends LaunchError {}
+
+/** The two variables a vendor's binary reads its identity from. */
+export interface IdentityEnv {
+  /** Names a subscription Account's config directory to the binary (`VENDOR_CONFIG_DIR_ENV`). */
+  configDir: string;
+  /** Carries an API-key Account's key to the binary. */
+  apiKey: string;
+}
+
+/**
+ * The Worker's environment for one Account: the inherited environment and the request's overrides
+ * with every identity variable removed, then the Account's one variable. Overrides are filtered like
+ * the inherited environment and applied before the Account's variable, so neither path can hand the
+ * Worker an identity other than the Account's. A key reaches the vendor under the one variable it
+ * reads and nothing else; the Foreman's own variable name is not the Worker's business. A
+ * `readonly-browser` turn loses `VERIFIER_STRIPPED_ENV` as well, before the Account's variable is
+ * set (that one it keeps: it is how the vendor bills the turn).
+ */
+export function buildWorkerEnv(
+  account: Account,
+  identity: IdentityEnv,
+  baseEnv: Readonly<Record<string, string | undefined>>,
+  overrides: Readonly<Record<string, string>> = {},
+  sandbox: TurnSandbox = "worker",
+): Record<string, string> {
+  let env: Record<string, string> = { ...withoutIdentityEnv(baseEnv), ...withoutIdentityEnv(overrides) };
+  if (sandbox === "readonly-browser") env = withoutVerifierEnv(env);
+  if (account.type === "subscription") {
+    env[identity.configDir] = account.configDir;
+  } else {
+    const key = baseEnv[account.keyRef];
+    if (key === undefined || key === "") {
+      throw new CredentialError(`Account "${account.name}" needs $${account.keyRef} set in the Foreman's environment`);
+    }
+    delete env[account.keyRef];
+    env[identity.apiKey] = key;
+  }
+  return env;
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Why a launch that threw before the process existed failed. Only a `CredentialError` — which the
+ * Foreman raised itself, about its own Account record — is credential; everything else is a machine
+ * that could not start the binary, and guessing otherwise is how a working Account gets quarantined. */
+export function launchFailureReason(error: unknown): TurnFailureReason {
+  return error instanceof CredentialError ? "credential_failed" : "launch_failed";
+}
+
+/** A turn that could not be launched at all: one `failed` event and nothing to stop. `launch_failed`
+ * unless the caller knows better; `launchFailureReason` is what both adapters ask. */
+export function failedHandle(message: string, reason: TurnFailureReason = "launch_failed"): TurnHandle {
+  return {
+    events: (async function* () {
+      yield { type: "failed", reason, message } as AdapterEvent;
+    })(),
+    stop: async () => undefined,
+  };
+}
+
+/** A `rate_limited` event with `resetAt` only when the vendor named one. */
+export function rateLimitedEvent(message: string, resetAt: string | undefined): AdapterEvent {
+  return resetAt === undefined ? { type: "rate_limited", message } : { type: "rate_limited", resetAt, message };
+}
+
+class AsyncQueue<T> implements AsyncIterable<T> {
+  private readonly items: T[] = [];
+  private waiting: (() => void) | null = null;
+  private closed = false;
+
+  push(item: T): void {
+    if (this.closed) return;
+    this.items.push(item);
+    this.waiting?.();
+  }
+
+  close(): void {
+    this.closed = true;
+    this.waiting?.();
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<T> {
+    for (;;) {
+      if (this.items.length > 0) {
+        yield this.items.shift()!;
+        continue;
+      }
+      if (this.closed) return;
+      await new Promise<void>((resolve) => {
+        this.waiting = resolve;
+      });
+      this.waiting = null;
+    }
+  }
+}
+
+export interface ProcessTurnSpec {
+  spawn: ProcessSpawner;
+  command: string;
+  args: string[];
+  options: SpawnOptions;
+  stallTimeoutMs: number | undefined;
+  /** Known before the process speaks when resuming; the vendor's first line confirms it. */
+  sessionId: string | undefined;
+  onLine: ((line: string) => void) | undefined;
+}
+
+/**
+ * One Worker process as the adapter's event stream. Subclasses translate the vendor's stream
+ * lines (`handleMessage`) and may release per-turn resources (`cleanup`); the base owns the
+ * process: it spawns, arms the stall timer on every chunk, reassembles lines split across chunks
+ * and multi-byte characters split across them, keeps a stderr tail for the exit that comes
+ * without a result, and reports `stalled`, `stopped` or `vendor_error` when the process ends
+ * before the subclass ended the turn.
+ */
+export abstract class ProcessTurn implements TurnHandle {
+  readonly events: AsyncIterable<AdapterEvent>;
+  protected sessionId: string | undefined;
+  private readonly queue = new AsyncQueue<AdapterEvent>();
+  private readonly decoder = new TextDecoder();
+  private process: SpawnedProcess | null = null;
+  private stallTimer: ReturnType<typeof setTimeout> | null = null;
+  private stoppedByCaller = false;
+  private stalled = false;
+  private ended = false;
+  private stderrTail = "";
+
+  protected constructor(protected readonly spec: ProcessTurnSpec) {
+    this.sessionId = spec.sessionId;
+    this.events = this.queue;
+  }
+
+  /** Starts the process; called by the subclass constructor once its own fields are set. */
+  protected begin(): void {
+    this.run().catch((error: unknown) => {
+      this.end({ type: "failed", reason: "vendor_error", message: errorMessage(error), sessionId: this.sessionId });
+    });
+  }
+
+  get pid(): number | undefined {
+    return this.process?.pid;
+  }
+
+  /** Kills the Worker whether or not the turn has ended, so a process that lingers after its result
+   * is not orphaned; the exit handler in run() reports `stopped` if the turn was still open. */
+  async stop(): Promise<void> {
+    this.stoppedByCaller = true;
+    this.process?.kill();
+  }
+
+  /** One parsed JSON line from the vendor's stdout. */
+  protected abstract handleMessage(line: unknown): void;
+
+  /** Called once, when the turn has ended for any reason. */
+  protected cleanup(): void {}
+
+  protected end(event: AdapterEvent): void {
+    if (this.ended) return;
+    this.ended = true;
+    this.clearStall();
+    this.queue.push(event);
+    this.queue.close();
+    this.cleanup();
+  }
+
+  protected emit(event: AdapterEvent): void {
+    if (!this.ended) this.queue.push(event);
+  }
+
+  private armStall(): void {
+    if (this.spec.stallTimeoutMs === undefined) return;
+    this.clearStall();
+    this.stallTimer = setTimeout(() => {
+      this.stalled = true;
+      this.emit({ type: "stalled", silentMs: this.spec.stallTimeoutMs! });
+      this.process?.kill();
+    }, this.spec.stallTimeoutMs);
+  }
+
+  private clearStall(): void {
+    if (this.stallTimer) clearTimeout(this.stallTimer);
+    this.stallTimer = null;
+  }
+
+  private decode(chunk: string | Uint8Array): string {
+    // One streaming decoder per turn: a multi-byte character may be split across two chunks.
+    return typeof chunk === "string" ? chunk : this.decoder.decode(chunk, { stream: true });
+  }
+
+  private async run(): Promise<void> {
+    try {
+      this.process = this.spec.spawn(this.spec.command, this.spec.args, this.spec.options);
+    } catch (error) {
+      this.end({ type: "failed", reason: "launch_failed", message: errorMessage(error) });
+      return;
+    }
+    this.armStall();
+    const stderr = this.drainStderr(this.process.stderr);
+    let remainder = "";
+    try {
+      for await (const chunk of this.process.stdout) {
+        this.armStall();
+        remainder += this.decode(chunk);
+        let newline = remainder.indexOf("\n");
+        while (newline !== -1) {
+          this.handleLine(remainder.slice(0, newline));
+          remainder = remainder.slice(newline + 1);
+          newline = remainder.indexOf("\n");
+        }
+      }
+      remainder += this.decoder.decode();
+      if (remainder.trim() !== "") this.handleLine(remainder);
+    } catch {
+      // A destroyed pipe after kill(): the exit below says what happened.
+    }
+    this.clearStall();
+    let exit: { code: number | null; signal: string | null };
+    try {
+      exit = await this.process.exited;
+    } catch (error) {
+      this.end({ type: "failed", reason: "launch_failed", message: `Could not start ${this.spec.command}: ${errorMessage(error)}` });
+      return;
+    }
+    await stderr;
+    if (this.ended) return;
+    if (this.stalled) {
+      this.end({ type: "failed", reason: "stalled", message: `No output for ${this.spec.stallTimeoutMs}ms; the Worker was stopped`, sessionId: this.sessionId });
+    } else if (this.stoppedByCaller) {
+      this.end({ type: "failed", reason: "stopped", message: "Stopped before the Worker reported", sessionId: this.sessionId });
+    } else {
+      const how = exit.signal ? `signal ${exit.signal}` : `code ${exit.code}`;
+      this.end({
+        type: "failed",
+        reason: "vendor_error",
+        message: `${this.spec.command} exited with ${how} before a result`,
+        sessionId: this.sessionId,
+        details: this.stderrTail ? [this.stderrTail] : undefined,
+      });
+    }
+  }
+
+  private async drainStderr(stream: AsyncIterable<string | Uint8Array>): Promise<void> {
+    const decoder = new TextDecoder();
+    try {
+      for await (const chunk of stream) {
+        const text = typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+        this.stderrTail = (this.stderrTail + text).slice(-2000).trim();
+      }
+    } catch {
+      // Same as stdout: a killed process may destroy the pipe.
+    }
+  }
+
+  private handleLine(raw: string): void {
+    const text = raw.trim();
+    if (text === "") return;
+    this.spec.onLine?.(text);
+    let line: unknown;
+    try {
+      line = JSON.parse(text);
+    } catch {
+      // Vendors occasionally print diagnostics on stdout; they are progress, not protocol.
+      this.emit({ type: "output", text });
+      return;
+    }
+    this.handleMessage(line);
+  }
+}

package/src/identity.ts

@@ -0,0 +1,49 @@
+import { Code, ConnectError, type Client } from "@connectrpc/connect";
+import type { UserService } from "@opsee/mcp-server/gen/api/v1/user_pb.js";
+
+/** Who the stored token belongs to, as the backend reports it. */
+export interface Identity {
+  userId: number;
+  fullName: string;
+  email: string;
+  companyId: number;
+  companyName: string;
+}
+
+/** The slice of the generated UserService client the CLI needs; tests supply a fake. */
+export type IdentityClient = Pick<Client<typeof UserService>, "getMe">;
+
+export async function fetchIdentity(users: IdentityClient): Promise<Identity> {
+  const res = await users.getMe({});
+  const u = res.user;
+  if (!u) {
+    throw new Error("Backend returned no user for this token");
+  }
+  return {
+    userId: u.id,
+    fullName: u.fullName,
+    email: u.email,
+    companyId: u.companyId,
+    companyName: u.company?.name ?? "",
+  };
+}
+
+/** Fetches the identity, or null when the backend says the token is not valid. Other failures
+ * (network, server errors) propagate: they are not evidence of a missing login. */
+export async function identityIfAuthorized(users: IdentityClient): Promise<Identity | null> {
+  try {
+    return await fetchIdentity(users);
+  } catch (error) {
+    if (error instanceof ConnectError && error.code === Code.Unauthenticated) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export function formatIdentity(id: Identity): string {
+  const company = id.companyName
+    ? `${id.companyName} (company ${id.companyId})`
+    : `company ${id.companyId}`;
+  return `${id.fullName} <${id.email}> (user ${id.userId}) at ${company}`;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import { main } from "./cli.js";
+
+main(process.argv.slice(2)).then((code) => process.exit(code));

package/src/init/managed.ts

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+
+/** The ownership marker every whole file `opsee init` writes carries. It records the hash of the
+ * content Opsee generated so a re-run can tell "still what we wrote" from "the user edited it".
+ * Two comment styles, because a marker must be a comment in the file's own syntax. */
+export type MarkerStyle = "markdown" | "yaml";
+
+const MARKER_RE = /^(?:<!-- |# )opsee:managed sha256:([0-9a-f]{64})(?: -->)?$/;
+
+export function hashOf(body: string): string {
+  return createHash("sha256").update(body, "utf8").digest("hex");
+}
+
+function markerLine(style: MarkerStyle, hash: string): string {
+  return style === "markdown" ? `<!-- opsee:managed sha256:${hash} -->` : `# opsee:managed sha256:${hash}`;
+}
+
+/** Where the marker goes: line 1, unless the file opens with YAML frontmatter, in which case it
+ * goes right after the closing `---` so the frontmatter parsers of Claude Code and Codex still
+ * see it first. The hash always covers the whole body, frontmatter included. */
+function splitFrontmatter(body: string): [string, string] {
+  const match = /^---\n[\s\S]*?\n---\n/.exec(body);
+  return match ? [match[0], body.slice(match[0].length)] : ["", body];
+}
+
+/** Generated content plus its marker: what `opsee init` writes to disk. */
+export function stamp(body: string, style: MarkerStyle): string {
+  const [front, rest] = splitFrontmatter(body);
+  return `${front}${markerLine(style, hashOf(body))}\n${rest}`;
+}
+
+export interface Marked {
+  hash: string;
+  /** The file with its marker line removed: what the hash was taken over. */
+  body: string;
+}
+
+/** Reads the marker back out of a file on disk; null when the file carries none. */
+export function parseMarker(content: string): Marked | null {
+  const lines = content.split("\n");
+  // The marker is on line 1 or directly after frontmatter; scanning the first few lines covers
+  // both without letting a marker quoted deep inside a document count.
+  const limit = Math.min(lines.length, 16);
+  for (let i = 0; i < limit; i++) {
+    const match = MARKER_RE.exec(lines[i]);
+    if (!match) continue;
+    if (i > 0 && !(lines[0] === "---" && lines[i - 1] === "---")) continue;
+    lines.splice(i, 1);
+    return { hash: match[1], body: lines.join("\n") };
+  }
+  return null;
+}
+
+export type WriteAction =
+  | "create"
+  | "update"
+  | "unchanged"
+  /** The file carries a marker but its content no longer matches: the user edited it. */
+  | "kept-edited"
+  /** The file exists and carries no marker: it was never ours. */
+  | "kept-unmanaged"
+  /** The file exists but cannot be merged into safely; `reason` says why. */
+  | "kept-invalid";
+
+/** What a re-run does with one path. Every writer (whole files, config merges, the pointer
+ * block) answers in this shape so the command reports them all the same way. */
+export interface WritePlan {
+  action: WriteAction;
+  /** What to write; present only for create and update. */
+  content?: string;
+  reason?: string;
+}
+
+/** Decides what a re-run does with one owned path. `existing` is the file's current content or
+ * null when absent; `generated` is the freshly rendered body without a marker. */
+export function planWrite(existing: string | null, generated: string, style: MarkerStyle): WritePlan {
+  const content = stamp(generated, style);
+  if (existing === null) return { action: "create", content };
+  const marked = parseMarker(existing);
+  if (!marked) return { action: "kept-unmanaged" };
+  if (hashOf(marked.body) !== marked.hash) return { action: "kept-edited" };
+  if (existing === content) return { action: "unchanged" };
+  return { action: "update", content };
+}