rovecode 0.4.0-beta.3 → 0.4.0

package/src/core/types.ts

@@ -0,0 +1,330 @@
+/** Rovecode core type contracts. Single source of truth for the runtime. */
+
+import type { ContextChunk } from "./context.ts";
+import type { CompactionStrategy, CompactionTrigger, PruneConfig } from "./compaction.ts";
+import type { OutputBudgetOptions } from "./tool-output-budget.ts";
+
+// ---------- Messages (harness-level; converted to provider form only at the seam) ----------
+
+export type Role = "system" | "user" | "assistant" | "tool";
+
+export interface TextPart { kind: "text"; text: string }
+export interface ToolCallPart { kind: "tool_call"; id: string; tool: string; args: unknown }
+export interface ToolResultPart { kind: "tool_result"; callId: string; ok: boolean; output: string }
+/** The four raster types both wire protocols accept (Anthropic image source media_type;
+ *  OpenAI image_url data URL) — decided by magic bytes, never by file extension (core/images.ts). */
+export type ImageMime = "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+/** port #34: an image attached to a user message. Exactly one carrier is set — `bytes` (base64,
+ *  the in-memory / transport form: TUI /attach, ACP image blocks) or `path` (the sidecar file the
+ *  session store wrote under `<session>/attachments/`; session-relative in entries.jsonl,
+ *  resolved to absolute on load). Adapters read either through core/images.ts imageData(). */
+export interface ImagePart {
+  kind: "image";
+  mime: ImageMime;
+  bytes?: string;
+  path?: string;
+  width?: number;
+  height?: number;
+  /** display name (the attached file's basename) — transcript chip + non-vision placeholder */
+  name?: string;
+}
+export type MessagePart = TextPart | ToolCallPart | ToolResultPart | ImagePart;
+
+export interface Message {
+  id: string;
+  role: Role;
+  parts: MessagePart[];
+  parentId: string | null;
+  createdAt: number;
+  /** provider+model that produced this message, when applicable */
+  origin?: { provider: string; model: string };
+  usage?: TokenUsage;
+}
+
+export interface TokenUsage { input: number; output: number; cacheRead?: number; cacheWrite?: number; costUsd?: number }
+
+// ---------- Provider seam (ADR-003: never throws; errors are stopReasons) ----------
+
+export type StopReason =
+  | "end_turn" | "tool_use" | "length" | "aborted" | "error" | "budget";
+
+export interface AssistantTurn {
+  parts: MessagePart[];
+  stopReason: StopReason;
+  usage: TokenUsage;
+  error?: string;
+}
+
+export interface StreamOptions {
+  signal?: AbortSignal;
+  /** the run's wall-clock deadline (epoch ms, RunConfig.maxSeconds) — a retry backoff that would end past it
+   *  is not taken (providers/retry.ts); unset = no clock */
+  deadlineAt?: number;
+  /** tool schemas advertised to the provider for native function calling */
+  tools?: ToolSchema[];
+}
+
+export interface StreamFn {
+  (model: ModelRef, messages: Message[], options?: StreamOptions): AsyncIterable<StreamEvent>;
+}
+
+export type StreamEvent =
+  | { type: "text_delta"; text: string }
+  /** a slice of the model's reasoning (Anthropic thinking_delta): counted for the live status
+   *  line, never part of the answer — the terminal turn's parts carry text and tool calls only */
+  | { type: "reasoning_delta"; text: string }
+  | { type: "tool_call_delta"; id: string; tool: string; argsDelta: string }
+  | { type: "turn"; turn: AssistantTurn };
+
+/** How hard the model is asked to think before it answers. `off` is the plain request; the three
+ *  levels map to each protocol's own dial — an Anthropic thinking budget in tokens, an OpenAI
+ *  `reasoning_effort` string (providers/stream.ts thinkingBudget). A model with no reasoning mode
+ *  ignores it: the field is sent, the endpoint drops it. */
+/** `auto` = send NO thinking field and let the provider's own default stand — for the Claude 5 family
+ *  that is adaptive thinking at high effort. It is the runtime default: the old default `off` sent an
+ *  explicit `thinking: disabled`, which switched OFF the reasoning Opus 5 and Sonnet 5 do on their own
+ *  and was a large part of "the model is not performing" (Berkay, 2026-09-04). `off` stays as the
+ *  explicit, deliberate choice. */
+export type ThinkingEffort = "auto" | "off" | "low" | "medium" | "high";
+export const THINKING_EFFORTS: readonly ThinkingEffort[] = ["auto", "off", "low", "medium", "high"];
+
+/** a level from a flag/env word; undefined when it names nothing (the caller keeps its default,
+ *  rather than silently reading a typo as "off") */
+export function parseEffort(v: string | undefined): ThinkingEffort | undefined {
+  const w = (v ?? "").trim().toLowerCase();
+  return (THINKING_EFFORTS as readonly string[]).includes(w) ? (w as ThinkingEffort) : undefined;
+}
+
+export interface ModelRef {
+  provider: string;
+  model: string;
+  maxTokens?: number;
+  effort?: ThinkingEffort;
+  /** the catalog's word on whether the model has a reasoning mode (models.dev `reasoning`), stamped by
+   *  cli/runtime.ts buildDef; `false` means no thinking field is ever sent (providers/thinking.ts).
+   *  Unset = unknown: the dial goes out in the endpoint's dialect and a model that cannot reason ignores it. */
+  reasoning?: boolean;
+}
+
+// ---------- Tools (ADR-005: validate → revise → policy → approve → sandbox → execute) ----------
+
+export interface ToolSchema {
+  name: string;
+  description: string;
+  /** JSON Schema for args */
+  args: Record<string, unknown>;
+}
+
+export type ToolKind = "read" | "write" | "execute" | "spawn" | "memory" | "network" | "custom";
+
+export interface ToolContext {
+  sessionId: string;
+  cwd: string;
+  signal: AbortSignal;
+  /** port #29: the run this call belongs to (hook ctx, tracing); unset for bare registry use */
+  runId?: string;
+  /** emit progress updates surfaced as tool_execution_update events */
+  onUpdate?: (note: string) => void;
+  /** spawn a child agent (multi-agent path) */
+  spawn?: (req: SpawnRequest) => Promise<SpawnResult>;
+  permissions: PermissionDecision;
+}
+
+export interface Tool {
+  schema: ToolSchema;
+  kind: ToolKind;
+  /** false → run concurrently with siblings in the same batch */
+  sequential?: boolean;
+  interruptible?: boolean;
+  /** Policy resource for a tool whose modes differ in what they are ALLOWED to do, where neither a
+   *  path, a command nor a URL says which mode this call is. Without it the resource falls back to the
+   *  tool NAME, so one rule has to cover every mode — which is how a read-only `design_direction
+   *  {"action":"get"}` came to raise an approval card (2026-09-04): it writes nothing, but it shares a
+   *  rule with `set`, and a human trained to allow the read hits allow on the write too. Return a short
+   *  stable word; a rule then targets it (`tool.design_direction get -> allow`). Never derive it from a
+   *  value the model can vary freely — the point is that a rule can name the mode, not that the model
+   *  can name its own permissions. */
+  resource?(args: unknown): string;
+  execute(args: unknown, ctx: ToolContext): Promise<ToolOutput>;
+}
+
+export interface ToolOutput { ok: boolean; output: string; data?: unknown }
+
+// ---------- Permissions ----------
+
+export type PermissionEffect = "allow" | "deny" | "prompt";
+
+export interface PermissionRule {
+  action: string;       // e.g. "file.write", "shell.exec", "spawn", "*"
+  resource: string;     // glob, e.g. "src/**", "rm *", "*"
+  effect: PermissionEffect;
+}
+
+export type PermissionDecision =
+  | { effect: "allow" }
+  | { effect: "deny"; reason: string }
+  | { effect: "prompt"; prompt: string };
+
+export type ApprovalFn = (req: ApprovalRequest) => Promise<"once" | "always" | "deny">;
+
+/** How much the human is asked. `ask` prompts for every write, command and subagent; `accept-edits`
+ *  stops asking for writes INSIDE the workspace (shell, spawn, network and writes outside it still
+ *  ask); `auto` never asks. Deny rules, plan mode and the execpolicy forbidden-argv stop hold at
+ *  every level — this dial only moves the prompt branch. */
+export type PermissionLevel = "ask" | "accept-edits" | "auto";
+
+export interface ApprovalRequest {
+  tool: string;
+  args: unknown;
+  revisedArgs: unknown;
+  reason: string;
+}
+
+// ---------- Events (loop output; also the durability + observability unit) ----------
+
+export type RunEvent =
+  | { type: "run_start"; runId: string; sessionId: string; goal: string }
+  | { type: "turn_start"; turn: number }
+  | { type: "message_update"; messageId: string; delta: string }
+  /** the provider turn is reasoning: `tokens` = estimated reasoning tokens so far this turn,
+   *  CUMULATIVE (a dropped event costs nothing). Only the count leaves the loop — the reasoning text
+   *  is not the answer and neither the transcript nor a client should carry it. */
+  | { type: "reasoning_update"; messageId: string; tokens: number }
+  | { type: "tool_execution_start"; callId: string; tool: string; args: unknown }
+  | { type: "tool_execution_update"; callId: string; note: string }
+  | { type: "tool_execution_end"; callId: string; ok: boolean; output: string; durationMs: number }
+  | { type: "tool_call_failed"; callId: string; reason: "truncated" | "invalid_args" | "permission_denied" | "not_found"; detail: string }
+  /** strategy = the one that RAN (core/compaction.ts seam, or "context-drop" for ADR-007 chunk
+   *  eviction); trigger (port #25) is set on history compactions only: "speculative" = estimate
+   *  crossed the threshold, "emergency" = the provider rejected the request as an overflow */
+  | { type: "compaction"; strategy: string; trigger?: CompactionTrigger; tokensBefore: number; tokensAfter: number }
+  | { type: "turn_end"; turn: number; stopReason: StopReason }
+  | { type: "steer"; text: string }
+  /** the verify gate is running the project's check / has finished it (core/verify-gate.ts); `detail` is one line */
+  | { type: "verify"; command: string; state: "running" | "passed" | "failed" | "timeout"; ms?: number; detail?: string }
+  /** `outstanding` (status "done" only): what the run left behind when the model stopped talking — absent
+   *  when nothing is notable AND at least one file was written, so a clean run's event is exactly what it
+   *  always was. "done" alone means "the model produced a turn with no tool call"; this field is how a
+   *  surface tells that from "the work is complete" (core/loop.ts assessOutstanding). */
+  | { type: "run_end"; status: "done" | "stopped" | "error" | "budget"; summary: string; outstanding?: RunOutstanding };
+
+/** What a run that ended as "done" left behind. Every field is a fact read from the transcript or the
+ *  session's own todo list — never an interpretation of the model's words. */
+export interface RunOutstanding {
+  /** tool calls of the LAST turn that had any, which failed: `write: Write rejected: …` (first line) */
+  failed: string[];
+  /** that last turn asked the user something and got no answer (headless, declined, or aborted) */
+  unansweredAsk: boolean;
+  /** successful `edit` + `write` calls over the whole run. `bash` may have changed files too; this counts only the two file tools */
+  writes: number;
+  /** the model's own todo list, when it kept one: items not completed / all items */
+  todosOpen?: number;
+  todosTotal?: number;
+  /** the finish check (core/loop.ts) asked once for the work to be finished; this run_end is the answer it got */
+  nudged: boolean;
+  /** the verify gate (core/verify-gate.ts), present when the run wrote files and a gate was wired: did the
+   *  project's own check pass after the changes, fail (with the failing part), time out, or was there no check to
+   *  run. Absent when nothing was written — and when files changed only through `bash`, which `writes` cannot see. */
+  verify?: VerifyState;
+}
+
+/** `refused`: what the resolver (core/verify.ts) saw and deliberately did not run, each with its reason — the
+ *  argument for trusting the gate. `reason` (unconfigured): why there is nothing to run, in the resolver's words. */
+export type VerifyState =
+  | { state: "unconfigured"; reason?: string; refused?: string[] }
+  | { state: "passed"; command: string; ms: number; refused?: string[] }
+  | { state: "failed"; command: string; code: number; failure: string; refused?: string[] }
+  | { state: "timeout"; command: string; seconds: number; refused?: string[] };
+
+/** RunConfig.verify — wired by the runtime, consumed by the loop's "done" exit. `resolution` is what
+ *  core/verify.ts decided (null / no commands = nothing to run → run_end says "not verified"); `run` executes it
+ *  bounded by `timeoutMs` and the run's abort (core/verify-gate.ts runVerify). */
+export interface VerifyGate {
+  resolution: { commands: string[]; refused?: string[]; source?: string; reason?: string } | null;
+  timeoutMs: number;
+  run: (signal: AbortSignal) => Promise<{ command: string; ok: boolean; code: number; timedOut: boolean; ms: number; failure: string; ran: number }>;
+}
+
+// ---------- Agent ----------
+
+export interface AgentDefinition {
+  name: string;
+  systemPrompt: string | ((ctx: AgentVars) => string);
+  tools: string[];        // tool names; "*" = all allowed by policy
+  model?: ModelRef;
+  maxTurns?: number;      // finite always (reject swarm's infinity)
+  spawns?: "none" | "siblings" | "subtasks";
+  memory?: { task?: boolean; episodic?: boolean; semantic?: boolean };
+  /** extra non-history ADR-007 chunks (port #8: harvested project config,
+   *  name "config", priority 70) folded into the system message via
+   *  assembleContext — droppable under budget pressure, unlike systemPrompt */
+  contextChunks?: ContextChunk[];
+}
+
+export interface AgentVars { [key: string]: unknown }
+
+export interface SpawnRequest {
+  agent: string;
+  goal: string;
+  vars?: AgentVars;
+  isolated?: boolean;     // COW/git worktree when writing
+  background?: boolean;
+}
+
+export interface SpawnResult { agent: string; ok: boolean; summary: string; usage: TokenUsage; patch?: string }
+
+// ---------- Run configuration ----------
+
+export interface RunConfig {
+  maxTurns: number;
+  /** wall-clock ceiling for one run, in seconds; checked at every turn boundary (core/loop.ts), so a
+   *  verification spiral of many short turns ends in a clean run_end "budget" with what was done so far.
+   *  Unset = no clock. `rovecode run` defaults it to 20 minutes; ROVECODE_MAX_SECONDS / --max-seconds set it. */
+  maxSeconds?: number;
+  /** a spend ceiling for one run, in US dollars, checked at every turn boundary like maxSeconds: the run ends
+   *  with status "budget" and what was done so far. Only turns `priceUsd` can price count; an unpriced turn
+   *  (a model the catalog does not know) adds nothing and the summary says how many there were. Unset = no cap.
+   *  `rovecode run --max-cost D`, ROVECODE_MAX_COST on every surface. */
+  maxCostUsd?: number;
+  /** what one turn cost, from its usage and the model that SERVED it (router fallback may differ from the one
+   *  asked for) — undefined when the catalog has no price. The runtime binds this to its catalog; without it
+   *  maxCostUsd can never trip, which is why buildCfg always sets both together. */
+  priceUsd?: (usage: TokenUsage, origin: ModelRef) => number | undefined;
+  /** The finish check (core/loop.ts, at the "done" exit): when the model stops talking right after a failed
+   *  tool call or an unanswered question to the user, ONE continuation turn names what is outstanding and asks
+   *  it to finish or say what is left. Default on; `false` (ROVECODE_FINISH_CHECK=0) turns it off. The
+   *  representation on run_end (`outstanding`) is unconditional — turning this off only stops the nudge. */
+  finishCheck?: boolean;
+  /** the model's own todo list for this session, read at the exit: open / total, or null when it kept none.
+   *  Represented on run_end; it is NOT a nudge trigger (no session on this machine has ever written one). */
+  todoState?: () => { open: number; total: number } | null;
+  /** The verify gate (core/verify-gate.ts): after a run that wrote files, run the project's own check before
+   *  "done"; a failure goes back to the model ONCE (sharing the finish check's one-nudge budget), then run_end
+   *  says how it ended. Absent = off (ROVECODE_VERIFY=0, plan mode, or a surface that wired none): nothing runs,
+   *  nothing is added, a run's event is byte-identical to one without the gate. */
+  verify?: VerifyGate;
+  contextBudgetTokens: number;
+  compactionThreshold: number;   // fraction of budget triggering compaction
+  /** port #25: history compaction strategy (core/compaction.ts; env ROVECODE_COMPACTION); default head-summarize */
+  compactionStrategy?: CompactionStrategy;
+  /** port #25 keep-window: user turns kept BEFORE the current one (default 2; an emergency keeps 0) */
+  compactionKeepTurns?: number;
+  /** P0-2: view-only prune of old tool outputs before each provider call (core/compaction.ts
+   *  pruneToolOutputs). The session record is NEVER rewritten — only the wire view is stubbed;
+   *  a `compaction` event with strategy "prune" is yielded (not persisted, same precedent as
+   *  "context-drop"). undefined = DEFAULT_PRUNE_CONFIG; false = off. */
+  prune?: PruneConfig | false;
+  /** P0-3: unified tool-output ceiling with UTF-8-safe head+tail truncation
+   *  (core/tool-output-budget.ts), applied by the loop to the persisted/next-request results.
+   *  undefined = the default ceiling; false = off (tool-side caps still apply). */
+  outputBudget?: OutputBudgetOptions | false;
+  /** P0-4: compaction thrash guard (core/compaction.ts CompactionPace). A compaction within this
+   *  many turns of the previous one earns one strike; one that fails to shrink the wire by ≥5%
+   *  earns another; COOLDOWN_STRIKES (3) stop compacting for the run, and an emergency arriving
+   *  during cooldown ends the run in error instead of re-driving. 0 = off.
+   *  Default DEFAULT_RAPID_WINDOW_TURNS (2). */
+  compactionRapidTurns?: number;
+  parallelTools: boolean;
+  permissionRules: PermissionRule[];
+  approval?: ApprovalFn;
+}

package/src/core/update-check.ts

@@ -0,0 +1,171 @@
+/** Is there a newer rovecode than the one running?
+ *
+ *  The release channel is GitHub Releases on 9Code-Labs/rovecode (Berkay's call, 2026-09-06). That
+ *  repository is private, so the check needs a token — and the honest consequence is written into the
+ *  result rather than hidden: with no token the answer is "unknown, and here is why", never "you are up
+ *  to date". A version check that reports "current" when it could not look is worse than no check, since
+ *  it is indistinguishable from a real answer.
+ *
+ *  Three rules, because this runs at startup:
+ *  - **It never blocks.** The caller fires it and paints; the answer arrives or it does not.
+ *  - **It never throws.** Offline, rate-limited, no token, a repository that has no releases yet — each
+ *    is a reason string, and the surface can decide whether to say anything.
+ *  - **It asks rarely.** The answer is cached in ~/.rovecode/update-check.json for six hours, so opening
+ *    the terminal twenty times in an afternoon is one request. A cache that cannot be read or written is
+ *    not an error either; it just means asking again. */
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { rovecodeHome } from "../providers/auth.ts";
+
+export interface UpdateStatus {
+  /** the version this process is */
+  current: string;
+  /** the newest release, when one could be read */
+  latest?: string;
+  /** true only when `latest` is genuinely newer than `current` */
+  newer: boolean;
+  /** why there is no `latest` — absent when the check succeeded */
+  reason?: string;
+  /** where the answer came from, so a stale line can be explained */
+  from: "network" | "cache";
+  /** the release page, for a surface that wants to point at it */
+  url?: string;
+}
+
+export interface UpdateCheckOptions {
+  repo?: string;
+  token?: string | undefined;
+  fetchFn?: typeof fetch;
+  /** overridden in tests; production caches under rovecodeHome() */
+  cacheFile?: string;
+  ttlMs?: number;
+  timeoutMs?: number;
+  now?: () => number;
+  /** answer from the cache or not at all — never open a socket. `rovecode --version` uses this: a courtesy
+   *  line must not make a command scripts call wait on a network round-trip (measured 3.2 s on a cold
+   *  cache before this existed, against 84–103 ms for everything else the command does). */
+  cacheOnly?: boolean;
+  /** last-resort token source; the default asks the gh CLI. Injected in tests so no process is spawned. */
+  ghToken?: () => Promise<string | undefined>;
+}
+
+const REPO = "9Code-Labs/rovecode";
+const TTL_MS = 6 * 60 * 60 * 1000;
+// 8s, not the 3s this started with. Nothing waits on this — the card is already painted and the notice
+// arrives when it arrives — so the only thing a short timeout buys is the wrong answer on exactly the run
+// that matters: measured cold on this machine the first api.github.com request took 12.7s and the next
+// 0.36s, which a 3s cap turns into "the check timed out" every single first start of the day.
+const TIMEOUT_MS = 8_000;
+
+/** semver-ish compare, tolerant of a leading v and of extra dot-parts; prerelease suffixes lose to the
+ *  same version without one, which is the conservative direction — it never invents an update. */
+export function isNewer(latest: string, current: string): boolean {
+  const parts = (v: string): { nums: number[]; pre: boolean } => {
+    const clean = v.trim().replace(/^v/i, "");
+    const [core = "", ...rest] = clean.split("-");
+    return { nums: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre: rest.length > 0 };
+  };
+  const a = parts(latest), b = parts(current);
+  const len = Math.max(a.nums.length, b.nums.length);
+  for (let i = 0; i < len; i++) {
+    const x = a.nums[i] ?? 0, y = b.nums[i] ?? 0;
+    if (x !== y) return x > y;
+  }
+  // same numbers: a prerelease is not newer than the release, and never newer than itself
+  return b.pre && !a.pre;
+}
+
+function readCache(file: string, ttlMs: number, now: number): UpdateStatus | null {
+  try {
+    const raw = JSON.parse(readFileSync(file, "utf8")) as { at?: number; status?: UpdateStatus };
+    if (typeof raw.at !== "number" || !raw.status) return null;
+    if (now - raw.at > ttlMs) return null;
+    return { ...raw.status, from: "cache" };
+  } catch {
+    return null;   // unreadable, missing, or written by an older shape — ask again
+  }
+}
+
+function writeCache(file: string, status: UpdateStatus, now: number): void {
+  try {
+    mkdirSync(join(file, ".."), { recursive: true });
+    writeFileSync(file, JSON.stringify({ at: now, status: { ...status, from: "network" } }));
+  } catch {
+    /* a read-only home must not turn a successful check into a failure */
+  }
+}
+
+/** `gh auth token`, or undefined for every way that can fail — no gh, not logged in, slow, noisy. This is
+ *  a convenience, so it is never allowed to become a reason the terminal waits. */
+function ghAuthToken(): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    try {
+      execFile("gh", ["auth", "token"], { timeout: 1_500, windowsHide: true }, (err, stdout) => {
+        const t = typeof stdout === "string" ? stdout.trim() : "";
+        resolve(err !== null || t.length === 0 ? undefined : t);
+      });
+    } catch { resolve(undefined); }
+  });
+}
+
+export async function checkForUpdate(current: string, opts: UpdateCheckOptions = {}): Promise<UpdateStatus> {
+  const now = (opts.now ?? Date.now)();
+  const cacheFile = opts.cacheFile ?? join(rovecodeHome(), "update-check.json");
+  const ttl = opts.ttlMs ?? TTL_MS;
+
+  const cached = readCache(cacheFile, ttl, now);
+  if (cached) return { ...cached, current, newer: cached.latest !== undefined && isNewer(cached.latest, current) };
+
+  // GITHUB_TOKEN, then GH_TOKEN, then whatever `gh auth login` already stored — most people who can read
+  // a private repository at all have the CLI logged in, and making them export a variable to be told about
+  // an update is a step they will not take. The token is used and dropped: it never enters the cache.
+  if (opts.cacheOnly === true) {
+    return { current, newer: false, from: "cache", reason: "not asked yet — rovecode checks at startup, at most once every six hours" };
+  }
+  const token = opts.token ?? process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? await (opts.ghToken ?? ghAuthToken)();
+  if (!token) {
+    // not cached: a token may appear before the next start, and caching "no token" would hide it
+    return { current, newer: false, from: "network", reason: "the release repository is private and no GITHUB_TOKEN is set (or `gh auth login`)" };
+  }
+
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), opts.timeoutMs ?? TIMEOUT_MS);
+  try {
+    const res = await (opts.fetchFn ?? fetch)(`https://api.github.com/repos/${opts.repo ?? REPO}/releases/latest`, {
+      headers: { accept: "application/vnd.github+json", authorization: `Bearer ${token}`, "user-agent": "rovecode" },
+      signal: ac.signal,
+    });
+    if (res.status === 404) {
+      const status: UpdateStatus = { current, newer: false, from: "network", reason: "no release published yet" };
+      writeCache(cacheFile, status, now);   // worth caching: it will stay true until someone publishes
+      return status;
+    }
+    if (!res.ok) return { current, newer: false, from: "network", reason: `GitHub answered ${res.status}` };
+    const body = (await res.json().catch(() => null)) as { tag_name?: string; html_url?: string } | null;
+    const tag = typeof body?.tag_name === "string" ? body.tag_name : undefined;
+    if (!tag) return { current, newer: false, from: "network", reason: "the release carries no tag name" };
+    const status: UpdateStatus = {
+      current, latest: tag.replace(/^v/i, ""), newer: isNewer(tag, current), from: "network",
+      ...(typeof body?.html_url === "string" ? { url: body.html_url } : {}),
+    };
+    writeCache(cacheFile, status, now);
+    return status;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { current, newer: false, from: "network", reason: ac.signal.aborted ? "the check timed out" : msg };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** The one line a surface shows, or null when there is nothing worth saying. Deliberately silent for
+ *  "up to date" and for every failure: a startup screen that reports its own plumbing every time trains
+ *  people to stop reading it. `verbose` is for `rovecode --version`, where asking WAS the point. */
+export function updateLine(s: UpdateStatus, verbose = false): string | null {
+  if (s.newer && s.latest !== undefined) return `update available: ${s.current} → ${s.latest}${s.url ? ` · ${s.url}` : ""}`;
+  if (!verbose) return null;
+  if (s.reason !== undefined) return `update check: ${s.reason}`;
+  return `up to date (${s.current})${s.from === "cache" ? " · cached" : ""}`;
+}

package/src/core/update.ts

@@ -0,0 +1,158 @@
+/** Self-update: how THIS installation gets to the newer release the update-check named.
+ *
+ *  Rovecode ships three ways and each updates differently, so the first job is honest detection
+ *  (core/update.ts detectInstallMode): an npm install (the published tarball — `npm install -g
+ *  rovecode@<channel>`), a source checkout (git pull + bun install, and build:cli when a dist was
+ *  built), or a compiled single binary (no self-swap yet: the release page's artifact is the answer,
+ *  said plainly rather than attempted and half-done). Detection is path arithmetic, injected and
+ *  testable; nothing here guesses from the version string alone.
+ *
+ *  The channel follows the running version unless told otherwise: a prerelease (0.4.0-beta.1) stays
+ *  on `beta`, a release stays on `latest` — an auto-update must never silently move someone between
+ *  channels.
+ *
+ *  `autoUpdate` (settings.json / ROVECODE_AUTO_UPDATE=1) runs the plan in the BACKGROUND at TUI
+ *  boot when the cached update-check says a newer version exists. It never blocks the session and
+ *  never swaps the running process: on Windows a live executable's files are being replaced under
+ *  it, so the honest promise is "updated — restart to run it", which is what the note says. */
+
+import { existsSync } from "node:fs";
+import { join, sep } from "node:path";
+
+export type InstallMode = "npm" | "source" | "binary" | "unknown";
+export type UpdateChannel = "beta" | "latest";
+
+export interface DetectedInstall {
+  mode: InstallMode;
+  /** the package root (npm: the rovecode dir under node_modules; source: the repo root) when known */
+  root?: string;
+  /** npm: the install sits under npm's global prefix (decides -g) */
+  npmGlobal?: boolean;
+}
+
+/** bun's compiled binaries run their modules from a virtual FS whose path starts with this */
+const BUNFS = "/$bunfs/";
+
+/** Where does the running entry live? `entry` is the main module's path (import.meta.path of the
+ *  CLI entry), `exec` the runtime's own (process.execPath), `npmGlobalPrefix` the answer of
+ *  `npm prefix -g` when the caller already has it (undefined = decide later, at run time). */
+export function detectInstallMode(paths: { entry: string; exec?: string; npmGlobalPrefix?: string }): DetectedInstall {
+  const entry = paths.entry.replace(/\\/g, "/");
+  if (entry.includes(BUNFS) || (paths.exec !== undefined && paths.exec.replace(/\\/g, "/").includes(BUNFS))) {
+    return { mode: "binary" };
+  }
+  const nm = entry.lastIndexOf("/node_modules/");
+  if (nm >= 0) {
+    // the package root is node_modules/<name> (a scoped name adds one segment)
+    const after = entry.slice(nm + "/node_modules/".length);
+    const segs = after.split("/");
+    const pkgSegs = after.startsWith("@") ? segs.slice(0, 2) : segs.slice(0, 1);
+    const root = entry.slice(0, nm) + "/node_modules/" + pkgSegs.join("/");
+    const prefix = paths.npmGlobalPrefix?.replace(/\\/g, "/").replace(/\/$/, "");
+    const npmGlobal = prefix !== undefined
+      ? root.toLowerCase().startsWith((prefix + "/node_modules/").toLowerCase())
+      : undefined;
+    return { mode: "npm", root, ...(npmGlobal !== undefined ? { npmGlobal } : {}) };
+  }
+  // a source checkout: the entry is src/cli/main.ts (or bin/…) inside a git repo
+  for (const cand of sourceRootCandidates(paths.entry)) {
+    if (existsSync(join(cand, ".git"))) return { mode: "source", root: cand };
+  }
+  return { mode: "unknown" };
+}
+
+/** walk up from the entry file to the plausible repo roots (bounded: an entry deep in a monorepo) */
+function sourceRootCandidates(entry: string): string[] {
+  const out: string[] = [];
+  let dir = entry.includes(sep) || entry.includes("/") ? entry.replace(/\\/g, "/").split("/").slice(0, -1).join("/") : ".";
+  for (let i = 0; i < 6 && dir.length > 0; i++) {
+    out.push(dir.replace(/\//g, sep));
+    const up = dir.split("/").slice(0, -1).join("/");
+    if (up === dir) break;
+    dir = up;
+  }
+  return out;
+}
+
+export interface UpdatePlan {
+  mode: InstallMode;
+  channel: UpdateChannel;
+  /** the commands to run, in order; empty for binary/unknown (manual carries the words) */
+  commands: string[][];
+  cwd?: string;
+  /** what a human does when there is no command to run */
+  manual?: string;
+}
+
+/** The channel: explicit wins; otherwise a prerelease stays on beta, a release stays on latest. */
+export function channelFor(currentVersion: string, explicit?: UpdateChannel | "auto"): UpdateChannel {
+  if (explicit === "beta" || explicit === "latest") return explicit;
+  return currentVersion.includes("-") ? "beta" : "latest";
+}
+
+export function planUpdate(install: DetectedInstall, opts: { currentVersion: string; channel?: UpdateChannel | "auto"; distBuilt?: boolean }): UpdatePlan {
+  const channel = channelFor(opts.currentVersion, opts.channel);
+  switch (install.mode) {
+    case "npm": {
+      const spec = `rovecode@${channel}`;
+      // -g when the install is global; a local (project) install updates in its project root.
+      // npmGlobal undefined = the caller did not resolve `npm prefix -g` yet: runUpdate decides.
+      if (install.npmGlobal === false && install.root) {
+        const root = install.root.replace(/\\/g, "/");
+        const i = root.lastIndexOf("/node_modules/");
+        const project = i > 0 ? root.slice(0, i).replace(/\//g, sep) : undefined;
+        return { mode: "npm", channel, commands: [["npm", "install", spec]], ...(project ? { cwd: project } : {}) };
+      }
+      return { mode: "npm", channel, commands: [["npm", "install", "-g", spec]] };
+    }
+    case "source": {
+      const cmds: string[][] = [["git", "pull", "--ff-only"], ["bun", "install"]];
+      if (opts.distBuilt === true) cmds.push(["bun", "run", "build:cli"]);
+      return { mode: "source", channel, commands: cmds, ...(install.root ? { cwd: install.root } : {}) };
+    }
+    case "binary":
+      return { mode: "binary", channel, commands: [], manual: "a compiled binary does not replace itself yet — download the new artifact from the releases page (https://github.com/9Code-Labs/rovecode-community/releases) and swap the file" };
+    default:
+      return { mode: "unknown", channel, commands: [], manual: "cannot tell how this copy was installed — update it the way you installed it (npm: `npm install -g rovecode@" + channel + "`; source: `git pull && bun install`)" };
+  }
+}
+
+export interface RunUpdateDeps {
+  /** run one command, stream-free: returns the exit code and the merged tail of its output */
+  spawn(cmd: string[], cwd?: string): Promise<{ code: number; out: string }>;
+  /** npm only, and only when the plan did not pre-decide: resolve `npm prefix -g` */
+  npmGlobalPrefix?(): Promise<string | undefined>;
+  log?(line: string): void;
+}
+
+export interface UpdateResult { ok: boolean; detail: string; ran: string[] }
+
+/** Run the plan's commands in order; the first failure stops and reports. Never throws. */
+export async function runUpdate(plan: UpdatePlan, install: DetectedInstall, deps: RunUpdateDeps): Promise<UpdateResult> {
+  const ran: string[] = [];
+  if (plan.commands.length === 0) return { ok: false, detail: plan.manual ?? "nothing to run", ran };
+  let commands = plan.commands;
+  // an npm plan whose -g question was left open: answer it now, once, from `npm prefix -g`
+  if (plan.mode === "npm" && install.npmGlobal === undefined && install.root && deps.npmGlobalPrefix) {
+    const prefix = (await deps.npmGlobalPrefix())?.replace(/\\/g, "/").replace(/\/$/, "");
+    if (prefix) {
+      const global = install.root.replace(/\\/g, "/").toLowerCase().startsWith((prefix + "/node_modules/").toLowerCase());
+      const spec = plan.commands[0]![plan.commands[0]!.length - 1]!;
+      commands = global ? [["npm", "install", "-g", spec]] : [["npm", "install", spec]];
+    }
+  }
+  for (const cmd of commands) {
+    deps.log?.(`$ ${cmd.join(" ")}`);
+    let r: { code: number; out: string };
+    try { r = await deps.spawn(cmd, plan.cwd); }
+    catch (e) { return { ok: false, detail: `${cmd[0]} failed to start: ${e instanceof Error ? e.message : String(e)}`, ran }; }
+    ran.push(cmd.join(" "));
+    if (r.code !== 0) return { ok: false, detail: `${cmd.join(" ")} exited ${r.code}: ${tail(r.out)}`, ran };
+  }
+  return { ok: true, detail: "updated — restart rovecode to run the new version", ran };
+}
+
+function tail(s: string, max = 400): string {
+  const t = s.trim();
+  return t.length > max ? "…" + t.slice(-max) : t;
+}