Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(ruflo-console): the header shows the git build; the console offers a newly published version and can auto-update (ADR 426, 428)

ruvc35f394733e3
diff --git a/plugins/ruflo-console/.claude-plugin/plugin.json b/plugins/ruflo-console/.claude-plugin/plugin.json
index 30eff9f975..ec2cae6bf5 100644
--- a/plugins/ruflo-console/.claude-plugin/plugin.json
+++ b/plugins/ruflo-console/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "ruflo-console",
- "description": "ruflo's cockpit inside Claude Code and the one /ruflo command for every ruflo mod (function hooks, early access). Views: overview with health alerts, swarm topology graph, claims flow with TTL rings, federation map, plugin health matrix, learning curve and pipeline, MetaHarness radar and audit trend, memory, cost gauge, agent timeline, approvals queue, event stream, a main menu, an x.ruv.io federation board, an AI terminal (codex, claude or both in remembered sessions, streamed), Skills (npx skills), a Hive-Mind view, a MetaHarness lab, agent drill-down; a command palette for confirm-gated actions through the ruflo CLI; a band above the prompt. Reads ruflo's files and the CLI's local JSON; anything not measured reads n/a; no network by default.",
+ "description": "ruflo's cockpit inside Claude Code and the one /ruflo command for every ruflo mod (function hooks, early access). Views: overview with health alerts, swarm topology graph, claims flow with TTL rings, federation map, plugin health matrix, learning curve and pipeline, MetaHarness radar and audit trend, memory, cost gauge, agent timeline, approvals queue, event stream, a main menu, an x.ruv.io federation board, an AI terminal (codex, claude or both in remembered sessions, streamed), Skills (npx skills), a Hive-Mind view, a MetaHarness lab, agent drill-down; a command palette for confirm-gated actions through the ruflo CLI; a band above the prompt. Reads ruflo's files and the CLI's local JSON; anything not measured reads n/a. The one network call it makes by itself is a daily read of the published plugin.json at github.com/ruvnet/ruflo to offer an update (Settings → Updates: ask, auto, or off); it installs only through Claude Code's own claude plugin update, and never a new major version without asking.",
"version": "0.26.0",
"author": {
"name": "ruvnet",
diff --git a/plugins/ruflo-console/hooks/bindings.ts b/plugins/ruflo-console/hooks/bindings.ts
index 699e37a4d0..e0ed1eb7e4 100644
--- a/plugins/ruflo-console/hooks/bindings.ts
+++ b/plugins/ruflo-console/hooks/bindings.ts
@@ -26,6 +26,8 @@ import type { Runner } from './runner'
import { skillActions } from './skills'
import { moreSkillActions } from './skills-lab'
import { CLI_PREFIXES, NAV_KEY, PANE_ID, viewOf, type State } from './state'
+import { runUpdateCheck } from './update-flow'
+import { UPDATES_KEY } from './updates'
import { vectorActions } from './vector'
import type { Actions } from './views/common'
import { openTasks, selection } from './views/select'
@@ -87,6 +89,16 @@ export function actionsOf(state: State, host: Host, runner: Runner, steps: Steps
void host.storeSet(NAV_KEY, style).catch(() => undefined)
host.invalidate()
},
+ updates: mode => {
+ state.updates = mode
+ void host.storeSet(UPDATES_KEY, mode).catch(() => undefined)
+ host.invalidate()
+ },
+ checkUpdates: () => {
+ state.updateNote = 'checking…'
+ host.invalidate()
+ void runUpdateCheck(state, host, { force: true })
+ },
editField: (key, text) => {
state.fieldText.set(key, text)
host.invalidate()
diff --git a/plugins/ruflo-console/hooks/build.ts b/plugins/ruflo-console/hooks/build.ts
new file mode 100644
index 0000000000..dc58ed4a66
--- /dev/null
+++ b/plugins/ruflo-console/hooks/build.ts
@@ -0,0 +1,24 @@
+/**
+ * Which build is running, for the header. The version is the same across every commit of a release, so on its own it cannot say
+ * whether a session has the latest code or a stale copy; the git revision can. A leaf with no imports (the drawing code reads it,
+ * `register.ts` sets it once the session starts). It is set only when the plugin folder is a `plugins/ruflo-console` checkout of the
+ * repo git reports, so an installed copy that happens to sit inside some other repository never shows that repository's commit.
+ */
+let held = ''
+
+export const setBuild = (id: string): void => {
+ held = id
+}
+
+export const getBuild = (): string => held
+
+/** The plugin folder's place in its repository that makes it ours: `git rev-parse --show-prefix` prints this for a checkout. */
+export const PLUGIN_PREFIX = 'plugins/ruflo-console'
+
+export const isOurCheckout = (showPrefix: string): boolean => showPrefix.trim().replace(/\/$/, '') === PLUGIN_PREFIX
+
+/**
+ * `git describe --always --dirty --abbrev=7` as a build id: a short revision, with `-dirty` when the tree has uncommitted edits.
+ * Anything else (an error message, escape codes, a long line) is refused, because this text is drawn on the screen.
+ */
+export const buildOf = (stdout: string): string => (/^[0-9a-f]{4,40}(-dirty)?$/.test(stdout.trim()) ? stdout.trim() : '')
diff --git a/plugins/ruflo-console/hooks/data/alerts.ts b/plugins/ruflo-console/hooks/data/alerts.ts
index bf64732b1d..6d37afa859 100644
--- a/plugins/ruflo-console/hooks/data/alerts.ts
+++ b/plugins/ruflo-console/hooks/data/alerts.ts
@@ -3,6 +3,7 @@
* command (or palette entry) that addresses it; each approval names what a person decides and how. Nothing here
* guesses: an agent is "stalled" only when ruflo marks it busy and the console has seen nothing of it for a while.
*/
+import { getBootChecks } from '../boot-checks'
import type { State } from '../state'
import type { ClaimRecord } from './parse'
import { RUFLO_MARKET } from './snapshot'
@@ -31,6 +32,14 @@ export function alertsOf(state: State, nowMs: number, loadedAtMs: number): Alert
const snap = state.snapshot
const out: Alert[] = []
+ // The self-check shows on the boot screen, which the plain look and a BBS look with the boot off never draw: a failed area is also an
+ // alert, so it is seen in every look, and before any project is read.
+ const failed = (getBootChecks() ?? []).filter(check => !check.ok)
+
+ if (failed.length > 0) {
+ out.push({ id: 'self-check', level: 'bad', text: `self-check: ${failed.map(check => check.area).join(', ')} failed — ${failed[0]?.problems[0] ?? ''}`.slice(0, 160), fix: 'npx vitest run plugins/ruflo-console/tests/self-check.spec.ts' })
+ }
+
if (snap === null) return out
const seen = lastSeen(state, loadedAtMs)
diff --git a/plugins/ruflo-console/hooks/gfx/pictures.ts b/plugins/ruflo-console/hooks/gfx/pictures.ts
index 0700473949..6aeb3b77b4 100644
--- a/plugins/ruflo-console/hooks/gfx/pictures.ts
+++ b/plugins/ruflo-console/hooks/gfx/pictures.ts
@@ -6,6 +6,7 @@
*/
import { Braille, COLOR, Grid, mix, ramp, sparkline } from './raster'
import { bigText } from './font'
+import { getBuild } from '../build'
import { CONSOLE_VERSION } from '../version'
export { bootPicture, BOOT_ROWS } from './boot'
@@ -263,7 +264,8 @@ export function bannerPicture(project: string, columns: number, t: number): Grid
const x0 = width + 2
if (columns > x0 + 4) {
- grid.text(x0, 0, `â–‘â–’â–“ AGENT SWARM CONSOLE v${CONSOLE_VERSION}`.slice(0, columns - x0), NEON_MAGENTA)
+ // The version, and the git revision when the session knows it: the revision changes with every commit, so it shows which build is loaded.
+ grid.text(x0, 0, `░▒▓ AGENT SWARM CONSOLE v${CONSOLE_VERSION}${getBuild() === '' ? '' : ` · ${getBuild()}`}`.slice(0, columns - x0), NEON_MAGENTA)
const node = `▸ npx ruflo · ${project}`.slice(0, columns - x0 - 2)
grid.text(x0, 1, node, NEON_CYAN)
diff --git a/plugins/ruflo-console/hooks/host.ts b/plugins/ruflo-console/hooks/host.ts
index 811b472576..0771452ae2 100644
--- a/plugins/ruflo-console/hooks/host.ts
+++ b/plugins/ruflo-console/hooks/host.ts
@@ -17,6 +17,12 @@ export type Host = {
after: (ms: number, fn: () => void) => Timer
storeGet: (key: string) => Promise<unknown>
storeSet: (key: string, value: unknown) => Promise<void>
+ /** A GET through the host (never the plugin's own network; an administrator's policy may refuse it): the status and the body text. */
+ fetchText: (url: string) => Promise<{ ok: boolean; status: number; text: string }>
+ /** The engine's own choice dialog: the label chosen. Rejects when dismissed, and when nobody can be asked (a -p run). */
+ askChoice: (question: string, options: readonly string[]) => Promise<string>
+ /** A short note over the transcript's corner; it leaves the transcript and the model untouched. */
+ toast: (text: string, timeoutMs?: number) => void
invalidate: () => void
/** Moves a pane's focus ring onto an element it drew (a field), while the pane holds the keys. */
focus: (paneId: string, key: string) => Promise<unknown>
diff --git a/plugins/ruflo-console/hooks/mission-guidance.ts b/plugins/ruflo-console/hooks/mission-guidance.ts
index 9f35811962..74f6e11aeb 100644
--- a/plugins/ruflo-console/hooks/mission-guidance.ts
+++ b/plugins/ruflo-console/hooks/mission-guidance.ts
@@ -139,11 +139,13 @@ export function startGuidance(state: State, host: Host, mc: McState): void {
mc.guidance = guidance
- // The section redraws while the run is going, so its spinner and clock move even before the first words arrive.
+ // The section redraws while the run is going, so its spinner and clock move even before the first words arrive. fps 0 is the
+ // person's choice of no animation and a closed pane has nothing to redraw, so neither is redrawn for it; the section still
+ // updates as words arrive.
const tick = (): void => {
if (guidance.status !== 'running') return
- host.invalidate()
+ if (state.options.fps > 0 && state.pane.isOpen) host.invalidate()
host.after(250, tick)
}
diff --git a/plugins/ruflo-console/hooks/register.ts b/plugins/ruflo-console/hooks/register.ts
index e5782ec300..e20e5ae5a8 100644
--- a/plugins/ruflo-console/hooks/register.ts
+++ b/plugins/ruflo-console/hooks/register.ts
@@ -11,6 +11,9 @@ import { ownerLine, ownerOf } from './tool-owner'
import { newState, PANE_ID, restore, restoreSessions, storeKeyOf, termStoreKeyOf } from './state'
import { BAR_KEY, barView } from './views/bar'
import { setBootChecks } from './boot-checks'
+import { buildOf, isOurCheckout, setBuild } from './build'
+import { runUpdateCheck } from './update-flow'
+import { parseMode, UPDATES_KEY } from './updates'
import { selfCheckResults } from './self-check'
import type { Kit } from './views/common'
import { picturesOf } from './views/frames'
@@ -41,6 +44,13 @@ function hostOf($: EngineInterface, cwd: string): Host {
after: (ms, fn) => $.clock.after(ms, fn),
storeGet: async key => $.store.get(key),
storeSet: async (key, value) => $.store.set(key, value as never),
+ fetchText: async url => {
+ const response = await $.http.fetch(url)
+
+ return { ok: response.ok, status: response.status, text: response.text }
+ },
+ askChoice: async (question, options) => $.ui.ask(question, options),
+ toast: (text, timeoutMs) => quietly(() => $.ui.toast(text, timeoutMs === undefined ? undefined : { timeoutMs })),
invalidate: () => quietly(() => $.ui.invalidate('ui.render')),
focus: async (paneId, key) => $.ui.focus({ requestId: paneId, key }),
blit: args => quietly(() => $.ui.blit(args)),
@@ -109,6 +119,34 @@ export const register: Register = (on, raw: PluginOptions) => {
state.isInteractive = e.isInteractive !== false
control = createController(state, host)
+ // Which build is this? Only a checkout of this plugin in its repository is read (an installed copy inside some other repo is not
+ // that repo's commit); read-only, $0, and any failure leaves the header at its version alone.
+ const here = host
+ const root = here.pluginRoot
+
+ const built = here
+ .run(['git', '-C', root, 'rev-parse', '--show-prefix'], 3_000)
+ .then(prefix => (prefix.exitCode === 0 && isOurCheckout(prefix.stdout) ? here.run(['git', '-C', root, 'describe', '--always', '--dirty', '--abbrev=7'], 3_000) : null))
+ .then(described => {
+ setBuild(described !== null && described.exitCode === 0 ? buildOf(described.stdout) : '')
+ here.invalidate()
+ })
+ .catch(() => undefined)
+
+ // The update mode is the person's, kept in the plugin's store; then, once the build is known (a development checkout is never offered
+ // an update) and the screen has settled, one check for a newer published version. It never throws and never blocks the console.
+ const moded = here.storeGet(UPDATES_KEY).then(
+ value => {
+ state.updates = parseMode(value)
+ here.invalidate()
+ },
+ () => undefined,
+ )
+
+ void Promise.all([built, moded]).then(() => {
+ if (state.isInteractive) here.after(2_500, () => void runUpdateCheck(state, here))
+ })
+
const bound = host
state.home = (await bound.home().catch(() => undefined)) ?? null
diff --git a/plugins/ruflo-console/hooks/state.ts b/plugins/ruflo-console/hooks/state.ts
index 3b4dce16c2..595fb77610 100644
--- a/plugins/ruflo-console/hooks/state.ts
+++ b/plugins/ruflo-console/hooks/state.ts
@@ -7,6 +7,7 @@ import type { ConsoleEvent } from './data/events'
import type { ReadCache } from './data/files'
import { emptyEvolve, type EvolveState } from './data/evolve'
import { emptySkills, type SkillsState } from './data/skills'
+import type { UpdatesMode } from './updates'
import { emptyMemoryLab, type MemoryLabState } from './memory-lab'
import { emptyVector, type VectorState } from './data/vector'
import type { Snapshot } from './data/snapshot'
@@ -206,6 +207,12 @@ export type State = {
allowed: Map<string, string>
/** The main nav's style, saved across sessions. */
nav: NavStyle
+ /** Whether to check for a newer published ruflo-console: ask first (the default), update without asking, or never check. Kept in the plugin's store. */
+ updates: UpdatesMode
+ /** What the last update check found, in a line, for Settings; empty until one has run. */
+ updateNote: string
+ /** A published version the person has not taken ("Not now"), shown on the band as a link to Settings; empty when there is none. */
+ updateAvailable: string
/** The nav group whose pages are showing, picked on this page (it follows the open page again once the page changes). */
navPick: { group: string; view: ViewId } | null
/** The nav search words (empty: no search). */
@@ -310,6 +317,9 @@ export function newState(raw: PluginOptions | undefined): State {
curveGrewAtMs: 0,
dockColumns: 0,
nav: 'auto',
+ updates: 'ask',
+ updateNote: '',
+ updateAvailable: '',
navPick: null,
navQuery: '',
turnActive: false,
diff --git a/plugins/ruflo-console/hooks/update-flow.ts b/plugins/ruflo-console/hooks/update-flow.ts
new file mode 100644
index 0000000000..3eab01f157
--- /dev/null
+++ b/plugins/ruflo-console/hooks/update-flow.ts
@@ -0,0 +1,217 @@
+/**
+ * The update check and install: at load (and on "check now" in Settings) it reads the manifest published to github.com/ruvnet/ruflo,
+ * and for a strictly newer version either asks (Update now, Always auto-update, Not now) or, if the person chose "always", installs
+ * without asking, except across a major version. The install is Claude Code's own `claude plugin marketplace update` and `claude
+ * plugin update`; this file never downloads or runs the new code itself, never passes `-y` or `--accept-command` (so Claude Code's
+ * confirmation for a marketplace-declared command stands), and checks the installed version afterwards instead of assuming it worked.
+ * Everything it needs comes in as `UpdateDeps`, so tests/update-flow.spec.ts drives every branch with no host and no network.
+ */
+import type { Host } from './host'
+import {
+ APPLYING_KEY,
+ bumpKind,
+ CHECKED_KEY,
+ decide,
+ firstLine,
+ INSTALLED_KEY,
+ installedEntry,
+ isBeingApplied,
+ isDue,
+ LABEL,
+ MANIFEST_URL,
+ MANUAL_COMMAND,
+ needsConfirmation,
+ PLUGIN_ID,
+ MARKET,
+ promptOf,
+ UPDATES_KEY,
+ versionFromManifest,
+ type UpdatesMode,
+} from './updates'
+import { getBuild } from './build'
+import { CONSOLE_VERSION } from './version'
+import type { State } from './state'
+
+export type RunResult = { exitCode: number | null; stdout: string; stderr: string }
+
+export type UpdateDeps = {
+ nowMs: () => number
+ /** A timer on the host's clock; the returned timer can be cancelled. */
+ after: Host['after']
+ /** The version this session is running. */
+ local: string
+ isInteractive: boolean
+ /** A development checkout (a session loaded from a git worktree) manages itself with git: it is never offered an update. */
+ isDevCheckout: () => boolean
+ mode: () => UpdatesMode
+ setMode: (mode: UpdatesMode) => Promise<void>
+ get: (key: string) => Promise<unknown>
+ set: (key: string, value: unknown) => Promise<void>
+ fetchText: Host['fetchText']
+ ask: Host['askChoice']
+ run: (argv: readonly string[], timeoutMs: number) => Promise<RunResult>
+ toast: (text: string, timeoutMs?: number) => void
+}
+
+export type UpdateOutcome = 'skipped' | 'current' | 'declined' | 'installed' | 'unverified' | 'failed'
+export type UpdateResult = { outcome: UpdateOutcome; remote?: string; detail: string }
+
+const FETCH_TIMEOUT_MS = 8_000
+const STEP_TIMEOUT_MS = 180_000
+const LIST_TIMEOUT_MS = 30_000
+
+const skipped = (detail: string): UpdateResult => ({ outcome: 'skipped', detail })
+
+/** The fetch, or a refusal after the timeout (on the host's clock: a mod has no setTimeout): a host that never answers must not hold the session. */
+const fetched = (deps: UpdateDeps): Promise<{ ok: boolean; status: number; text: string }> =>
+ new Promise((resolve, reject) => {
+ const timer = deps.after(FETCH_TIMEOUT_MS, () => reject(new Error('timed out')))
+
+ deps.fetchText(MANIFEST_URL).then(
+ response => {
+ timer.cancel()
+ resolve(response)
+ },
+ error => {
+ timer.cancel()
+ reject(error)
+ },
+ )
+ })
+
+async function listInstalled(deps: UpdateDeps) {
+ const listed = await deps.run(['claude', 'plugin', 'list', '--json'], LIST_TIMEOUT_MS).catch(() => null)
+
+ return listed === null || listed.exitCode !== 0 ? null : installedEntry(listed.stdout)
+}
+
+/** Installs `remote` with Claude Code's own commands, then reads back what is installed. Never throws. */
+export async function applyUpdate(deps: UpdateDeps, remote: string): Promise<UpdateResult> {
+ await deps.set(APPLYING_KEY, deps.nowMs())
+
+ try {
+ const before = await listInstalled(deps)
+
+ if (before === null) return { outcome: 'failed', remote, detail: `${PLUGIN_ID} is not installed from the ruflo marketplace here (a session loaded with --plugin-dir has nothing to update)` }
+
+ const market = await deps.run(['claude', 'plugin', 'marketplace', 'update', MARKET], STEP_TIMEOUT_MS).catch(() => null)
+
+ if (market === null || market.exitCode !== 0) return { outcome: 'failed', remote, detail: `the marketplace did not update: ${firstLine(`${market?.stderr ?? ''}\n${market?.stdout ?? ''}`) || 'no answer'}` }
+
+ // No -y and no --accept-command, ever: a marketplace-declared command is Claude Code's to confirm with a person.
+ const updated = await deps.run(['claude', 'plugin', 'update', PLUGIN_ID, '--scope', before.scope], STEP_TIMEOUT_MS).catch(() => null)
+ const output = `${updated?.stderr ?? ''}\n${updated?.stdout ?? ''}`
+
+ if (updated !== null && updated.exitCode !== 0 && needsConfirmation(output)) return { outcome: 'failed', remote, detail: `Claude Code wants you to confirm this update itself: run \`${MANUAL_COMMAND}\` in a terminal` }
+ if (updated === null || updated.exitCode !== 0) return { outcome: 'failed', remote, detail: `claude plugin update failed: ${firstLine(output) || 'no answer'}` }
+
+ const after = await listInstalled(deps)
+
+ if (after !== null && after.version === remote) {
+ await deps.set(INSTALLED_KEY, remote)
+
+ return { outcome: 'installed', remote, detail: `${remote} installed: restart Claude Code, or run /reload-plugins, to load it` }
+ }
+
+ return { outcome: 'unverified', remote, detail: `the update ran, but Claude Code lists ${after?.version ?? 'no version'} (expected ${remote}): check /plugin, then restart` }
+ } finally {
+ await deps.set(APPLYING_KEY, 0).catch(() => undefined)
+ }
+}
+
+/**
+ * One check. `force` is the person's own "check now": it ignores the daily gate and an off setting (they asked), but not a development
+ * checkout. Never throws: every failure is a result, and the console starts whatever happens here.
+ */
+export async function checkForUpdate(deps: UpdateDeps, options: { force?: boolean } = {}): Promise<UpdateResult> {
+ try {
+ const force = options.force === true
+ const mode = deps.mode()
+
+ if (!deps.isInteractive) return skipped('nobody to ask (not an interactive session)')
+ if (mode === 'off' && !force) return skipped('update checks are off')
+ if (deps.isDevCheckout()) return skipped('this session runs a development checkout, which updates with git')
+
+ const now = deps.nowMs()
+
+ if (!force && !isDue(await deps.get(CHECKED_KEY), now)) return skipped('checked in the last day')
+ if (!force && isBeingApplied(await deps.get(APPLYING_KEY), now)) return skipped('another session is updating')
+
+ const response = await fetched(deps).catch(() => null)
+
+ if (response === null || !response.ok) return { outcome: 'failed', detail: response === null ? 'could not reach GitHub' : `GitHub answered ${response.status}` }
+
+ const remote = versionFromManifest(response.text)
+
+ if (remote === null) return { outcome: 'failed', detail: 'the published manifest is not one of ours' }
+
+ await deps.set(CHECKED_KEY, now)
+
+ const kind = bumpKind(deps.local, remote)
+
+ if (kind === null) return { outcome: 'current', remote, detail: `${deps.local} is the newest published` }
+ if ((await deps.get(INSTALLED_KEY)) === remote) return skipped(`${remote} is installed: restart Claude Code to load it`)
+
+ // "Check now" with checks off still asks: the person asked, but off means nothing is installed without them.
+ const decision = decide(mode === 'off' ? 'ask' : mode, kind)
+
+ if (decision === 'ask') {
+ const prompt = promptOf(deps.local, remote, kind)
+ const choice = await deps.ask(prompt.question, prompt.options).catch(() => null)
+
+ if (choice === LABEL.always && kind !== 'major') await deps.setMode('auto')
+ else if (choice !== LABEL.now) return { outcome: 'declined', remote, detail: `${remote} is available; not now` }
+ } else {
+ deps.toast(`Updating ruflo-console to ${remote}…`)
+ }
+
+ const result = await applyUpdate(deps, remote)
+
+ deps.toast(result.outcome === 'installed' ? `ruflo-console ${result.detail}` : `ruflo-console update: ${result.detail}`, result.outcome === 'installed' ? 10_000 : 8_000)
+
+ return result
+ } catch (error) {
+ return { outcome: 'failed', detail: firstLine(error instanceof Error ? error.message : String(error)) || 'the check failed' }
+ }
+}
+
+/** The real dependencies: the host's storage, fetch, dialog and process runner, this session's mode, and the running version. */
+export function updateDeps(state: State, host: Host): UpdateDeps {
+ return {
+ nowMs: () => Date.now(),
+ after: (ms, fn) => host.after(ms, fn),
+ local: CONSOLE_VERSION,
+ isInteractive: state.isInteractive,
+ isDevCheckout: () => getBuild() !== '',
+ mode: () => state.updates,
+ setMode: async mode => {
+ state.updates = mode
+ await host.storeSet(UPDATES_KEY, mode)
+ host.invalidate()
+ },
+ get: key => host.storeGet(key),
+ set: (key, value) => host.storeSet(key, value),
+ fetchText: url => host.fetchText(url),
+ ask: (question, options) => host.askChoice(question, options),
+ run: async (argv, timeoutMs) => {
+ const result = await host.run(argv, timeoutMs)
+
+ return { exitCode: result.exitCode ?? null, stdout: result.stdout, stderr: result.stderr }
+ },
+ toast: (text, timeoutMs) => host.toast(text, timeoutMs),
+ }
+}
+
+/** Runs a check with the real dependencies and leaves its outcome in a line for Settings. */
+export async function runUpdateCheck(state: State, host: Host, options: { force?: boolean } = {}): Promise<UpdateResult> {
+ const result = await checkForUpdate(updateDeps(state, host), options)
+
+ state.updateNote = result.detail
+ // A declined version stays on the band as a link to Settings; installing it, or finding nothing newer, clears it. A skipped
+ // check says nothing about it either way.
+ if (result.outcome === 'declined') state.updateAvailable = result.remote ?? ''
+ else if (result.outcome === 'installed' || result.outcome === 'current' || result.outcome === 'unverified') state.updateAvailable = ''
+ host.invalidate()
+
+ return result
+}
diff --git a/plugins/ruflo-console/hooks/updates.ts b/plugins/ruflo-console/hooks/updates.ts
new file mode 100644
index 0000000000..0436e3ced5
--- /dev/null
+++ b/plugins/ruflo-console/hooks/updates.ts
@@ -0,0 +1,134 @@
+/**
+ * Updates, pure: when a newer ruflo-console is published to github.com/ruvnet/ruflo, offer it at load, and keep an "always" choice.
+ * Versions, the published manifest, the rules for what to do (ask, update without asking, leave alone), the question, and a read of
+ * `claude plugin list --json` live here with no host and no network, so tests/updates.spec.ts runs them. The flow that fetches and
+ * installs is hooks/update-flow.ts. The install itself is Claude Code's own `claude plugin update`, never code of ours, and its own
+ * confirmation for a marketplace-declared command is never bypassed (no `-y`, no `--accept-command`).
+ */
+import { RUFLO_MARKET } from './data/snapshot'
+
+export type UpdatesMode = 'ask' | 'auto' | 'off'
+export const UPDATES_MODES: readonly UpdatesMode[] = ['ask', 'auto', 'off']
+
+export const parseMode = (value: unknown): UpdatesMode => (value === 'auto' || value === 'off' ? value : 'ask')
+
+/** Keys in the plugin's store (shared across sessions): the mode, when it last checked, when a session began updating, what it installed. */
+export const UPDATES_KEY = 'updates'
+export const CHECKED_KEY = 'update-checked-at'
+export const APPLYING_KEY = 'update-applying-at'
+export const INSTALLED_KEY = 'update-installed'
+
+export const PLUGIN_NAME = 'ruflo-console'
+/** The marketplace the plugin is installed from (`claude plugin marketplace list`: ruflo, GitHub ruvnet/ruflo). */
+export const MARKET = RUFLO_MARKET
+export const PLUGIN_ID = `${PLUGIN_NAME}@${MARKET}`
+/** The published manifest: the same repository the ruflo marketplace is added from (ruvnet/ruflo), its main branch. */
+export const MANIFEST_URL = 'https://raw.githubusercontent.com/ruvnet/ruflo/main/plugins/ruflo-console/.claude-plugin/plugin.json'
+/** How often a session checks (the answer is cached across sessions), and how long one session's "I am updating" holds the others off. */
+export const CHECK_EVERY_MS = 24 * 60 * 60_000
+export const APPLYING_HOLD_MS = 10 * 60_000
+
+export const LABEL = { now: 'Update now', always: 'Always auto-update', later: 'Not now' } as const
+
+/** The command to type by hand, said whenever Claude Code asks for its own confirmation or the update cannot be done from here. */
+export const MANUAL_COMMAND = `claude plugin update ${PLUGIN_ID}`
+
+type Semver = readonly [number, number, number]
+
+/** `major.minor.patch` and nothing else: a pre-release or build suffix is never offered. */
+export function parseSemver(text: string): Semver | null {
+ const match = /^(\d{1,4})\.(\d{1,4})\.(\d{1,4})$/.exec(text.trim())
+
+ return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+export type Bump = 'patch' | 'minor' | 'major'
+
+/** What `remote` is over `local`, or null when it is not strictly newer (the same, older, or not a version): never a downgrade. */
+export function bumpKind(local: string, remote: string): Bump | null {
+ const a = parseSemver(local)
+ const b = parseSemver(remote)
+
+ if (a === null || b === null) return null
+ if (b[0] !== a[0]) return b[0] > a[0] ? 'major' : null
+ if (b[1] !== a[1]) return b[1] > a[1] ? 'minor' : null
+
+ return b[2] > a[2] ? 'patch' : null
+}
+
+/** The version in a fetched manifest, only if it is ours (`name` is ruflo-console) and a plain semver; else null. */
+export function versionFromManifest(text: string): string | null {
+ try {
+ const value = JSON.parse(text) as { name?: unknown; version?: unknown }
+
+ return value.name === PLUGIN_NAME && typeof value.version === 'string' && parseSemver(value.version) !== null ? value.version.trim() : null
+ } catch {
+ return null
+ }
+}
+
+/** Time to check: never has, a day has passed, or the stored time is in the future (a clock that moved). */
+export const isDue = (lastMs: unknown, nowMs: number): boolean => typeof lastMs !== 'number' || !Number.isFinite(lastMs) || lastMs > nowMs || nowMs - lastMs >= CHECK_EVERY_MS
+
+/** Another session began updating a moment ago: this one leaves it alone (best effort; the store is not atomic). */
+export const isBeingApplied = (startedMs: unknown, nowMs: number): boolean => typeof startedMs === 'number' && Number.isFinite(startedMs) && startedMs <= nowMs && nowMs - startedMs < APPLYING_HOLD_MS
+
+export type Decision = 'none' | 'ask' | 'auto'
+
+/**
+ * What to do with a newer version. Off does nothing. Auto updates without asking, but never across a major version: a new major can
+ * change what the console does, so it always asks. Otherwise it asks.
+ */
+export function decide(mode: UpdatesMode, kind: Bump | null): Decision {
+ if (kind === null || mode === 'off') return 'none'
+
+ return mode === 'auto' && kind !== 'major' ? 'auto' : 'ask'
+}
+
+/**
+ * The question and the choices. "Always" is offered only below a major version, and says exactly what it means; the question ends
+ * in a question mark, as the dialog requires.
+ */
+export function promptOf(local: string, remote: string, kind: Bump): { question: string; options: string[] } {
+ const intro = `ruflo-console ${remote} is published to github.com/ruvnet/ruflo (you have ${local}${kind === 'major' ? '; a new major version, which can change what the console does' : ''}).`
+ const always = kind === 'major' ? '' : `\n\n"${LABEL.always}" installs every new minor or patch version published there without asking (a new major version always asks). You can turn it off in Settings.`
+ const how = '\n\nIt runs claude plugin marketplace update, then claude plugin update, and takes effect after you restart Claude Code or run /reload-plugins.'
+
+ return { question: `${intro}${always}${how}\n\n${LABEL.now}?`, options: kind === 'major' ? [LABEL.now, LABEL.later] : [LABEL.now, LABEL.always, LABEL.later] }
+}
+
+export type Installed = { version: string; scope: string }
+
+/**
+ * Our plugin in `claude plugin list --json`: the user-scope entry if there is one, else an enabled one, else the first. Null when it is
+ * not installed from the marketplace (a session loaded with --plugin-dir has nothing to update) or the output is not the list.
+ */
+export function installedEntry(listJson: string, id: string = PLUGIN_ID): Installed | null {
+ try {
+ const list = JSON.parse(listJson) as unknown
+
+ if (!Array.isArray(list)) return null
+
+ const ours = list.filter((entry): entry is { id: string; version?: unknown; scope?: unknown; enabled?: unknown } => typeof entry === 'object' && entry !== null && (entry as { id?: unknown }).id === id)
+ const chosen = ours.find(entry => entry.scope === 'user') ?? ours.find(entry => entry.enabled === true) ?? ours[0]
+
+ return chosen === undefined || typeof chosen.version !== 'string' || typeof chosen.scope !== 'string' ? null : { version: chosen.version, scope: chosen.scope }
+ } catch {
+ return null
+ }
+}
+
+/** Claude Code refuses to run a marketplace-declared command unattended and says so: that is its trust gate, not a failure to retry. */
+export const needsConfirmation = (output: string): boolean => /shownCommand|must be confirmed|confirm/i.test(output)
+
+/** One short line of a command's output, for the toast: escapes and control characters removed, cut to fit. */
+export function firstLine(text: string, max = 140): string {
+ const line =
+ text
+ .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '')
+ .split('\n')
+ .map(entry => entry.replace(/[\u0000-\u001f\u007f‪-‮]/g, '').trim())
+ .find(entry => entry !== '') ?? ''
+
+ return line.length > max ? `${line.slice(0, max - 1)}…` : line
+}
diff --git a/plugins/ruflo-console/hooks/views/common.ts b/plugins/ruflo-console/hooks/views/common.ts
index 730b463bf4..cd44c8cbf7 100644
--- a/plugins/ruflo-console/hooks/views/common.ts
+++ b/plugins/ruflo-console/hooks/views/common.ts
@@ -24,6 +24,7 @@ import type { SkillActions } from '../skills'
import { START_LABEL, type StartId } from '../starts'
import type { MoreSkillActions } from '../skills-lab'
import { VIEWS, type HarnessId, type NavStyle, type State, type ViewId } from '../state'
+import type { UpdatesMode } from '../updates'
import type { VectorActions } from '../vector'
export type Kit = Pick<Elements['terminal'], 'Box' | 'Text' | 'Button'> & { Raster?: Elements['terminal']['Raster']; Input?: Elements['terminal']['Input'] }
@@ -97,6 +98,10 @@ export type Actions = {
navigator: NavActions
/** Sets how the main nav spells its tabs (saved). */
nav: (style: NavStyle) => void
+ /** Sets whether to check for a newer published ruflo-console: ask first, update without asking, or never (saved). */
+ updates: (mode: UpdatesMode) => void
+ /** Checks now, whatever the daily gate or an off setting says (it still asks before installing, and skips a development checkout). */
+ checkUpdates: () => void
/** Opens or closes a collapsible section (`<view>/<id>`). */
toggle: (key: string) => void
/** Settings: the level, a plugin, an option or ruflo config change (each asks first), AI preferences, and â–¸ ask claude/codex. */
diff --git a/plugins/ruflo-console/hooks/views/frames.ts b/plugins/ruflo-console/hooks/views/frames.ts
index d43e7c724d..54a5d90be2 100644
--- a/plugins/ruflo-console/hooks/views/frames.ts
+++ b/plugins/ruflo-console/hooks/views/frames.ts
@@ -7,6 +7,8 @@ import type { AuditTrend, HarnessScore, Intelligence } from '../data/cli'
import { recentByAgent } from '../data/events'
import { agentLabels } from '../data/parse'
import { getBootChecks } from '../boot-checks'
+import { getBuild } from '../build'
+import { CONSOLE_VERSION } from '../version'
import type { Snapshot } from '../data/snapshot'
import type { Channels, Peers, Roster } from '../data/cli'
import { pipelinePicture, radarPicture, samplesPicture, trendPicture, gaugePicture, type Stage } from '../gfx/charts'
@@ -133,7 +135,7 @@ export function picturesOf(state: State, columns: number, nowMs: number, t: numb
if (!isCompactPane(state) && state.view === 'menu') {
const project = state.cwd.split('/').filter(Boolean).at(-1) ?? ''
- pictures.set('header', state.options.look === 'bbs' ? bannerPicture(project, Math.min(width, 72), t) : headerPicture(`◆ ruflo · ${project}`, Math.min(width, 40), t))
+ pictures.set('header', state.options.look === 'bbs' ? bannerPicture(project, Math.min(width, 72), t) : headerPicture(`◆ ruflo v${CONSOLE_VERSION}${getBuild() === '' ? '' : ` · ${getBuild()}`} · ${project}`, Math.min(width, 64), t))
}
// BBS: every view's name as ANSI-style block art under the tabs, compact or not (the neon sign is the boot's alone).
diff --git a/plugins/ruflo-console/hooks/views/settings.ts b/plugins/ruflo-console/hooks/views/settings.ts
index 928806d439..65655f6846 100644
--- a/plugins/ruflo-console/hooks/views/settings.ts
+++ b/plugins/ruflo-console/hooks/views/settings.ts
@@ -3,6 +3,7 @@ import type { RenderElement } from 'claude-code'
import { catalogOf } from '../plugin-catalog'
import { AI_BUDGETS, CLAUDE_MODELS, CORE, DEFAULT_AI, pluginNames, SIMPLE, settingsOf, type CoreKey, type Level, type PluginConfig } from '../settings'
import { NAV_STYLES } from '../state'
+import { UPDATES_MODES, type UpdatesMode } from '../updates'
import { button, clip, col, row, rule, section, text, THEME, type Ctx } from './common'
/** One setting, whatever it belongs to, so a search, a level and "changed only" filter one list. */
@@ -190,6 +191,39 @@ function uiItems(ctx: Ctx): Item[] {
where: 'the console’s main nav',
}),
},
+ {
+ id: 'ui-updates',
+ source: 'UI',
+ title: 'Updates',
+ haystack: `updates update auto-update automatic version new published github check ${ctx.state.updates}`,
+ level: 'simple',
+ changed: ctx.state.updates !== 'ask',
+ rows: () => [
+ ...settingRows(ctx, {
+ key: 'ui-updates',
+ title: 'Updates',
+ description:
+ 'when a newer ruflo-console is published to github.com/ruvnet/ruflo: ask (offer it at load), auto (install a new minor or patch version without asking; a new major version still asks), or off (never look). One small request to GitHub a day; the install is Claude Code’s own claude plugin update, and takes effect after a restart',
+ current: ctx.state.updates,
+ isChanged: ctx.state.updates !== 'ask',
+ choices: UPDATES_MODES,
+ defaultText: 'default ask',
+ onChoice: value => ctx.act.updates(value as UpdatesMode),
+ fieldKey: 'st-ui-in-updates',
+ fieldLabel: 'updates',
+ fieldHint: '',
+ where: 'the console’s update check',
+ }),
+ row(
+ ctx,
+ [
+ button(ctx, 'updates-check-now', '↻ check for an update now', () => ctx.act.checkUpdates(), { primary: true }),
+ text(ctx, ` ${ctx.state.updateNote === '' ? 'it asks before installing, whatever the setting' : ctx.state.updateNote}`, { dimColor: true }),
+ ],
+ 'updates-check-row',
+ ),
+ ],
+ },
]
}
diff --git a/plugins/ruflo-console/tests/self-check.spec.ts b/plugins/ruflo-console/tests/self-check.spec.ts
index b2c535c328..fc8f348dc9 100644
--- a/plugins/ruflo-console/tests/self-check.spec.ts
+++ b/plugins/ruflo-console/tests/self-check.spec.ts
@@ -3,11 +3,13 @@
* entry fails (a pass that cannot fail would prove nothing). Run with
* npx vitest run plugins/ruflo-console/tests/self-check.spec.ts
*/
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
+import { setBootChecks } from '../hooks/boot-checks'
+import { alertsOf } from '../hooks/data/alerts'
import { BOOT_MODULES } from '../hooks/gfx/boot'
import { AREA_VIEW, REGISTRIES, selfCheck, selfCheckResults, type Registries } from '../hooks/self-check'
-import { VIEWS } from '../hooks/state'
+import { newState, VIEWS } from '../hooks/state'
const failing = (results: ReturnType<typeof selfCheck>) => results.filter(result => !result.ok)
const area = (results: ReturnType<typeof selfCheck>, name: string) => results.find(result => result.area === name)
@@ -38,6 +40,34 @@ describe('self-check: the real console', () => {
})
})
+describe('self-check: seen in every look, not only on the boot screen', () => {
+ afterEach(() => setBootChecks(undefined))
+
+ it('a failed area is an Overview alert, even before any project is read, so the plain look and a boot-off BBS look see it', () => {
+ const state = newState({})
+
+ expect(state.snapshot).toBeNull()
+
+ setBootChecks([{ area: 'Missions', ok: true, problems: [] }, { area: 'Security', ok: false, problems: ['aid-check: an empty field must be refused'] }])
+
+ const alert = alertsOf(state, 0, 0).find(entry => entry.id === 'self-check')
+
+ expect(alert?.level).toBe('bad')
+ expect(alert?.text).toContain('Security failed')
+ expect(alert?.text).toContain('aid-check: an empty field must be refused')
+ expect(alert?.text).not.toContain('Missions')
+ })
+
+ it('is no alert when every area passed, or when nothing has run the check', () => {
+ const state = newState({})
+
+ setBootChecks(selfCheck().map(result => ({ area: result.area, ok: result.ok, problems: result.problems })))
+ expect(alertsOf(state, 0, 0).some(entry => entry.id === 'self-check')).toBe(false)
+ setBootChecks(undefined)
+ expect(alertsOf(state, 0, 0).some(entry => entry.id === 'self-check')).toBe(false)
+ })
+})
+
describe('self-check: it fails on what is broken', () => {
const broken = (change: (registries: Registries) => Registries) => selfCheck(change(REGISTRIES))
diff --git a/plugins/ruflo-console/tests/updates.spec.ts b/plugins/ruflo-console/tests/updates.spec.ts
new file mode 100644
index 0000000000..84d9cb6c31
--- /dev/null
+++ b/plugins/ruflo-console/tests/updates.spec.ts
@@ -0,0 +1,442 @@
+/**
+ * Updates: the pure rules (versions, the manifest, what to do, the question, the installed list), then the whole flow driven with
+ * fakes (no host, no network): when it checks, what it asks, what it runs, what it refuses, and that it never claims an install it
+ * has not read back. Run with
+ * npx vitest run plugins/ruflo-console/tests/updates.spec.ts
+ */
+import { describe, expect, it } from 'vitest'
+
+import { applyUpdate, checkForUpdate, type RunResult, type UpdateDeps } from '../hooks/update-flow'
+import {
+ APPLYING_HOLD_MS,
+ APPLYING_KEY,
+ bumpKind,
+ CHECK_EVERY_MS,
+ CHECKED_KEY,
+ decide,
+ firstLine,
+ INSTALLED_KEY,
+ installedEntry,
+ isBeingApplied,
+ isDue,
+ LABEL,
+ MANUAL_COMMAND,
+ parseMode,
+ parseSemver,
+ PLUGIN_ID,
+ promptOf,
+ versionFromManifest,
+} from '../hooks/updates'
+
+const NOW = 1_800_000_000_000
+
+describe('versions', () => {
+ it('reads major.minor.patch and nothing else', () => {
+ expect(parseSemver('0.26.0')).toEqual([0, 26, 0])
+ expect(parseSemver(' 1.2.3 ')).toEqual([1, 2, 3])
+ for (const bad of ['1.2', '1.2.3-alpha.1', '1.2.3+build', 'v1.2.3', '', 'x.y.z', '1.2.3.4', '99999.0.0']) expect(parseSemver(bad), bad).toBeNull()
+ })
+
+ it('says what a newer version is, and nothing for the same, an older one, or a non-version: never a downgrade', () => {
+ expect(bumpKind('0.26.0', '0.26.1')).toBe('patch')
+ expect(bumpKind('0.26.0', '0.27.0')).toBe('minor')
+ expect(bumpKind('0.26.5', '0.27.0')).toBe('minor')
+ expect(bumpKind('0.26.0', '1.0.0')).toBe('major')
+ expect(bumpKind('0.26.0', '0.26.0')).toBeNull()
+ expect(bumpKind('0.26.1', '0.26.0')).toBeNull()
+ expect(bumpKind('0.27.0', '0.26.9')).toBeNull()
+ expect(bumpKind('1.0.0', '0.99.0')).toBeNull()
+ expect(bumpKind('0.26.0', '0.27.0-rc.1')).toBeNull()
+ expect(bumpKind('garbage', '0.27.0')).toBeNull()
+ })
+})
+
+describe('the published manifest', () => {
+ it('gives the version only when the manifest is ours and a plain version', () => {
+ expect(versionFromManifest(JSON.stringify({ name: 'ruflo-console', version: '0.27.0' }))).toBe('0.27.0')
+ expect(versionFromManifest(JSON.stringify({ name: 'something-else', version: '9.9.9' }))).toBeNull()
+ expect(versionFromManifest(JSON.stringify({ name: 'ruflo-console', version: '0.27.0-beta' }))).toBeNull()
+ expect(versionFromManifest(JSON.stringify({ name: 'ruflo-console' }))).toBeNull()
+ expect(versionFromManifest('<html>404</html>')).toBeNull()
+ expect(versionFromManifest('')).toBeNull()
+ })
+})
+
+describe('when to check, and what to do', () => {
+ it('checks when it never has, a day has passed, or the stored time is in the future', () => {
+ expect(isDue(undefined, NOW)).toBe(true)
+ expect(isDue('yesterday', NOW)).toBe(true)
+ expect(isDue(NOW - CHECK_EVERY_MS, NOW)).toBe(true)
+ expect(isDue(NOW - CHECK_EVERY_MS + 1, NOW)).toBe(false)
+ expect(isDue(NOW + 5_000, NOW)).toBe(true)
+ })
+
+ it('holds off while another session is updating, for a few minutes, not for ever', () => {
+ expect(isBeingApplied(NOW - 1_000, NOW)).toBe(true)
+ expect(isBeingApplied(NOW - APPLYING_HOLD_MS, NOW)).toBe(false)
+ expect(isBeingApplied(0, NOW)).toBe(false)
+ expect(isBeingApplied(undefined, NOW)).toBe(false)
+ })
+
+ it('off does nothing; ask asks; auto installs without asking, but a major version always asks', () => {
+ expect(decide('off', 'patch')).toBe('none')
+ expect(decide('ask', null)).toBe('none')
+ expect(decide('auto', null)).toBe('none')
+ expect(decide('ask', 'patch')).toBe('ask')
+ expect(decide('ask', 'major')).toBe('ask')
+ expect(decide('auto', 'patch')).toBe('auto')
+ expect(decide('auto', 'minor')).toBe('auto')
+ expect(decide('auto', 'major')).toBe('ask')
+ })
+
+ it('keeps ask unless the stored value is exactly auto or off', () => {
+ expect(parseMode('auto')).toBe('auto')
+ expect(parseMode('off')).toBe('off')
+ for (const other of ['ask', 'yes', undefined, null, 1, '']) expect(parseMode(other)).toBe('ask')
+ })
+})
+
+describe('the question', () => {
+ it('offers Update now, Always and Not now below a major version, says what Always means, and ends in a question mark', () => {
+ const { question, options } = promptOf('0.26.0', '0.27.0', 'minor')
+
+ expect(options).toEqual([LABEL.now, LABEL.always, LABEL.later])
+ expect(question).toContain('0.27.0')
+ expect(question).toContain('github.com/ruvnet/ruflo')
+ expect(question).toContain('without asking')
+ expect(question).toContain('a new major version always asks')
+ expect(question).toContain('Settings')
+ expect(question.trimEnd().endsWith('?')).toBe(true)
+ })
+
+ it('offers no Always for a major version, and says it is one', () => {
+ const { question, options } = promptOf('0.26.0', '1.0.0', 'major')
+
+ expect(options).toEqual([LABEL.now, LABEL.later])
+ expect(question).toContain('major version')
+ expect(question).not.toContain('Always auto-update')
+ })
+})
+
+describe('the installed list', () => {
+ const entry = (over: Record<string, unknown>) => ({ id: PLUGIN_ID, version: '0.26.0', scope: 'user', enabled: true, ...over })
+
+ it('prefers the user-scope entry, then an enabled one, then the first; and ignores other plugins', () => {
+ expect(installedEntry(JSON.stringify([entry({ scope: 'project', version: '0.1.0' }), entry({ scope: 'user', version: '0.2.0' })]))).toEqual({ version: '0.2.0', scope: 'user' })
+ expect(installedEntry(JSON.stringify([entry({ scope: 'project', enabled: false, version: '0.1.0' }), entry({ scope: 'local', version: '0.3.0' })]))).toEqual({ version: '0.3.0', scope: 'local' })
+ expect(installedEntry(JSON.stringify([entry({ id: 'ruflo-adr@ruflo', version: '9.9.9' })]))).toBeNull()
+ })
+
+ it('is null for output that is not the list, or an entry without a version or scope', () => {
+ expect(installedEntry('')).toBeNull()
+ expect(installedEntry('{"id":"x"}')).toBeNull()
+ expect(installedEntry('[]')).toBeNull()
+ expect(installedEntry(JSON.stringify([entry({ version: undefined })]))).toBeNull()
+ expect(installedEntry(JSON.stringify([entry({ scope: undefined })]))).toBeNull()
+ })
+})
+
+describe('a line of output', () => {
+ it('takes the first line with escapes, control characters and bidirectional marks removed, cut to fit', () => {
+ expect(firstLine('\u001b[31mfailed\u001b[0m: no network\nsecond')).toBe('failed: no network')
+ expect(firstLine('\n\n real‮ line')).toBe('real line')
+ expect(firstLine('x'.repeat(300)).length).toBe(140)
+ expect(firstLine('')).toBe('')
+ })
+})
+
+/** A scripted session: what the store holds, what GitHub says, what the person picks, and how each command answers. */
+type Script = {
+ mode?: UpdateDeps['mode'] extends () => infer M ? M : never
+ store?: Record<string, unknown>
+ manifest?: string | 'reject' | 'hang'
+ published?: string
+ choice?: string | 'reject'
+ listed?: string[]
+ isDev?: boolean
+ interactive?: boolean
+ marketExit?: number
+ updateExit?: number
+ updateOut?: string
+}
+
+function session(script: Script = {}) {
+ const store = new Map<string, unknown>(Object.entries(script.store ?? {}))
+ let mode = script.mode ?? 'ask'
+ const log = { fetches: 0, asked: [] as { question: string; options: readonly string[] }[], ran: [] as string[][], toasts: [] as string[], writes: [] as [string, unknown][] }
+ const lists = [...(script.listed ?? [JSON.stringify([{ id: PLUGIN_ID, version: '0.26.0', scope: 'user', enabled: true }]), JSON.stringify([{ id: PLUGIN_ID, version: script.published ?? '0.27.0', scope: 'user', enabled: true }])])]
+ const run = async (argv: readonly string[]): Promise<RunResult> => {
+ log.ran.push([...argv])
+
+ const text = argv.join(' ')
+
+ if (text === 'claude plugin list --json') return { exitCode: 0, stdout: lists.length > 1 ? (lists.shift() as string) : (lists[0] as string), stderr: '' }
+ if (text.startsWith('claude plugin marketplace update')) return { exitCode: script.marketExit ?? 0, stdout: 'updated', stderr: script.marketExit ? 'git: could not resolve host' : '' }
+
+ return { exitCode: script.updateExit ?? 0, stdout: script.updateOut ?? 'updated', stderr: '' }
+ }
+ const deps: UpdateDeps = {
+ nowMs: () => NOW,
+ after: (_ms, fn) => {
+ if (script.manifest === 'hang') fn()
+
+ return { cancel: () => undefined } as never
+ },
+ local: '0.26.0',
+ isInteractive: script.interactive ?? true,
+ isDevCheckout: () => script.isDev ?? false,
+ mode: () => mode,
+ setMode: async next => {
+ mode = next
+ log.writes.push(['updates', next])
+ },
+ get: async key => store.get(key),
+ set: async (key, value) => {
+ store.set(key, value)
+ log.writes.push([key, value])
+ },
+ fetchText: async () => {
+ log.fetches++
+
+ if (script.manifest === 'reject') throw new Error('network down')
+ if (script.manifest === 'hang') return new Promise(() => undefined)
+
+ return { ok: true, status: 200, text: script.manifest ?? JSON.stringify({ name: 'ruflo-console', version: script.published ?? '0.27.0' }) }
+ },
+ ask: async (question, options) => {
+ log.asked.push({ question, options })
+
+ if (script.choice === 'reject' || script.choice === undefined) throw new Error('dismissed')
+
+ return script.choice
+ },
+ run,
+ toast: text => void log.toasts.push(text),
+ }
+
+ return { deps, log, store, modeNow: () => mode }
+}
+
+describe('the flow: when it does not even look', () => {
+ it('does nothing when updates are off, in a non-interactive run, or in a development checkout', async () => {
+ for (const script of [{ mode: 'off' as const }, { interactive: false }, { isDev: true }]) {
+ const s = session(script)
+ const result = await checkForUpdate(s.deps)
+
+ expect(result.outcome, JSON.stringify(script)).toBe('skipped')
+ expect(s.log.fetches).toBe(0)
+ expect(s.log.ran).toEqual([])
+ }
+ })
+
+ it('looks at most once a day, and not while another session is updating', async () => {
+ const recent = session({ store: { [CHECKED_KEY]: NOW - 1_000 } })
+ const busy = session({ store: { [APPLYING_KEY]: NOW - 1_000 } })
+ const stale = session({ store: { [CHECKED_KEY]: NOW - CHECK_EVERY_MS - 1 }, choice: LABEL.later })
+
+ expect((await checkForUpdate(recent.deps)).outcome).toBe('skipped')
+ expect((await checkForUpdate(busy.deps)).outcome).toBe('skipped')
+ expect(recent.log.fetches + busy.log.fetches).toBe(0)
+ expect((await checkForUpdate(stale.deps)).outcome).toBe('declined')
+ expect(stale.log.fetches).toBe(1)
+ })
+
+ it('skips a version that is already installed and waiting for a restart, rather than asking again', async () => {
+ const s = session({ store: { [INSTALLED_KEY]: '0.27.0' } })
+
+ expect((await checkForUpdate(s.deps)).outcome).toBe('skipped')
+ expect(s.log.asked).toEqual([])
+ })
+})
+
+describe('the flow: what GitHub says', () => {
+ it('is current when nothing newer is published, and remembers it looked', async () => {
+ for (const published of ['0.26.0', '0.25.9']) {
+ const s = session({ published })
+ const result = await checkForUpdate(s.deps)
+
+ expect(result.outcome, published).toBe('current')
+ expect(s.log.asked).toEqual([])
+ expect(s.store.get(CHECKED_KEY)).toBe(NOW)
+ }
+ })
+
+ it('fails quietly, and tries again next time, when GitHub cannot be reached, hangs, or sends something that is not our manifest', async () => {
+ for (const manifest of ['reject', 'hang', '{"name":"someone-else","version":"9.0.0"}', 'not json'] as const) {
+ const s = session({ manifest })
+ const result = await checkForUpdate(s.deps)
+
+ expect(result.outcome, manifest).toBe('failed')
+ expect(s.log.asked).toEqual([])
+ expect(s.log.ran).toEqual([])
+ expect(s.store.has(CHECKED_KEY), manifest).toBe(false)
+ }
+ })
+
+ it('never throws, even when the store does', async () => {
+ const s = session()
+
+ s.deps.get = async () => {
+ throw new Error('store is broken')
+ }
+
+ expect((await checkForUpdate(s.deps)).outcome).toBe('failed')
+ })
+})
+
+describe('the flow: asking', () => {
+ it('Not now, a dismissed dialog, and anything typed under Other install nothing', async () => {
+ for (const choice of [LABEL.later, 'reject', 'sure, why not']) {
+ const s = session({ choice })
+ const result = await checkForUpdate(s.deps)
+
+ expect(result.outcome, choice).toBe('declined')
+ expect(s.log.ran, choice).toEqual([])
+ expect(s.modeNow(), choice).toBe('ask')
+ }
+ })
+
+ it('asks with the three choices and installs on Update now, leaving the mode as it was', async () => {
+ const s = session({ choice: LABEL.now })
+ const result = await checkForUpdate(s.deps)
+
+ expect(s.log.asked[0]?.options).toEqual([LABEL.now, LABEL.always, LABEL.later])
+ expect(result.outcome).toBe('installed')
+ expect(s.modeNow()).toBe('ask')
+ expect(s.store.get(INSTALLED_KEY)).toBe('0.27.0')
+ expect(s.log.toasts.at(-1)).toContain('restart Claude Code')
+ })
+
+ it('runs the marketplace update and then the plugin update in the scope it is installed in, and reads the list before and after', async () => {
+ const s = session({ choice: LABEL.now })
+
+ await checkForUpdate(s.deps)
+ expect(s.log.ran).toEqual([
+ ['claude', 'plugin', 'list', '--json'],
+ ['claude', 'plugin', 'marketplace', 'update', 'ruflo'],
+ ['claude', 'plugin', 'update', PLUGIN_ID, '--scope', 'user'],
+ ['claude', 'plugin', 'list', '--json'],
+ ])
+ })
+
+ it('Always auto-update turns it on, and installs this one', async () => {
+ const s = session({ choice: LABEL.always })
+ const result = await checkForUpdate(s.deps)
+
+ expect(s.modeNow()).toBe('auto')
+ expect(s.log.writes).toContainEqual(['updates', 'auto'])
+ expect(result.outcome).toBe('installed')
+ })
+})
+
+describe('the flow: always', () => {
+ it('installs a minor or patch version without asking, saying so first', async () => {
+ for (const published of ['0.27.0', '0.26.1']) {
+ const s = session({ mode: 'auto', published })
+ const result = await checkForUpdate(s.deps)
+
+ expect(result.outcome, published).toBe('installed')
+ expect(s.log.asked, published).toEqual([])
+ expect(s.log.toasts[0], published).toContain('Updating ruflo-console')
+ }
+ })
+
+ it('still asks for a major version, and offers no Always there', async () => {
+ const s = session({ mode: 'auto', published: '1.0.0', choice: LABEL.later })
+ const result = await checkForUpdate(s.deps)
+
+ expect(result.outcome).toBe('declined')
+ expect(s.log.asked[0]?.options).toEqual([LABEL.now, LABEL.later])
+ expect(s.log.ran).toEqual([])
+ })
+
+ it('"Always" cannot be picked for a major version even if the dialog returns it', async () => {
+ const s = session({ mode: 'ask', published: '1.0.0', choice: LABEL.always })
+ const result = await checkForUpdate(s.deps)
+
+ expect(result.outcome).toBe('declined')
+ expect(s.modeNow()).toBe('ask')
+ })
+})
+
+describe('the flow: "check now"', () => {
+ it('ignores the daily gate and an off setting, but still asks and still skips a development checkout', async () => {
+ const off = session({ mode: 'off', store: { [CHECKED_KEY]: NOW - 1_000 }, choice: LABEL.now })
+ const dev = session({ mode: 'off', isDev: true })
+
+ expect((await checkForUpdate(off.deps, { force: true })).outcome).toBe('installed')
+ expect(off.log.asked).toHaveLength(1)
+ expect(off.modeNow()).toBe('off')
+ expect((await checkForUpdate(dev.deps, { force: true })).outcome).toBe('skipped')
+ expect(dev.log.fetches).toBe(0)
+ })
+})
+
+describe('the flow: what it will not do, and what it will not claim', () => {
+ it('never passes -y or --accept-command to Claude Code, in any run', async () => {
+ for (const script of [{ choice: LABEL.now }, { mode: 'auto' as const }, { choice: LABEL.now, updateExit: 1, updateOut: 'shownCommand sha256 abc' }]) {
+ const s = session(script)
+
+ await checkForUpdate(s.deps)
+ for (const argv of s.log.ran) {
+ expect(argv).not.toContain('-y')
+ expect(argv).not.toContain('--yes')
+ expect(argv).not.toContain('--accept-command')
+ }
+ }
+ })
+
+ it("leaves Claude Code's own confirmation to the person, and says the command to run", async () => {
+ const s = session({ choice: LABEL.now, updateExit: 1, updateOut: 'a marketplace-declared command must be confirmed: shownCommand sha256 abc' })
+ const result = await checkForUpdate(s.deps)
+
+ expect(result.outcome).toBe('failed')
+ expect(result.detail).toContain(MANUAL_COMMAND)
+ expect(s.store.has(INSTALLED_KEY)).toBe(false)
+ })
+
+ it('does not call it installed when the list afterwards still shows the old version', async () => {
+ const s = session({ choice: LABEL.now, listed: [JSON.stringify([{ id: PLUGIN_ID, version: '0.26.0', scope: 'user', enabled: true }])] })
+ const result = await checkForUpdate(s.deps)
+
+ expect(result.outcome).toBe('unverified')
+ expect(result.detail).toContain('0.26.0')
+ expect(s.store.has(INSTALLED_KEY)).toBe(false)
+ expect(s.log.toasts.at(-1)).not.toContain('installed')
+ })
+
+ it('has nothing to update when the plugin is not installed from the marketplace (a --plugin-dir session), and runs no update', async () => {
+ const s = session({ choice: LABEL.now, listed: ['[]'] })
+ const result = await checkForUpdate(s.deps)
+
+ expect(result.outcome).toBe('failed')
+ expect(result.detail).toContain('--plugin-dir')
+ expect(s.log.ran).toEqual([['claude', 'plugin', 'list', '--json']])
+ })
+
+ it('stops, and says why, when the marketplace will not update', async () => {
+ const s = session({ choice: LABEL.now, marketExit: 1 })
+ const result = await checkForUpdate(s.deps)
+
+ expect(result.outcome).toBe('failed')
+ expect(result.detail).toContain('could not resolve host')
+ expect(s.log.ran.some(argv => argv[2] === 'update')).toBe(false)
+ })
+
+ it('always lets the other sessions go again, whether the install worked or not', async () => {
+ for (const script of [{ choice: LABEL.now }, { choice: LABEL.now, marketExit: 1 }, { choice: LABEL.now, listed: ['[]'] }]) {
+ const s = session(script)
+
+ await checkForUpdate(s.deps)
+ expect(s.store.get(APPLYING_KEY), JSON.stringify(script)).toBe(0)
+ }
+ })
+
+ it('applyUpdate alone reads the list before it touches anything', async () => {
+ const s = session({ listed: ['not json'] })
+ const result = await applyUpdate(s.deps, '0.27.0')
+
+ expect(result.outcome).toBe('failed')
+ expect(s.log.ran).toEqual([['claude', 'plugin', 'list', '--json']])
+ })
+})
diff --git a/plugins/ruflo-console/tests/version.spec.ts b/plugins/ruflo-console/tests/version.spec.ts
index a644633ee9..55388e7ad5 100644
--- a/plugins/ruflo-console/tests/version.spec.ts
+++ b/plugins/ruflo-console/tests/version.spec.ts
@@ -1,13 +1,24 @@
/**
- * The version the console shows is the plugin's manifest version. Run with
+ * The version the console shows is the plugin's manifest version, and the header adds the git revision so a session can tell which
+ * build it has: the version is the same across every commit of a release. Run with
* npx vitest run plugins/ruflo-console/tests/version.spec.ts
*/
import { readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
+import { buildOf, getBuild, isOurCheckout, setBuild } from '../hooks/build'
+import { bannerPicture } from '../hooks/gfx/pictures'
+import { newState } from '../hooks/state'
import { CONSOLE_VERSION } from '../hooks/version'
+import { picturesOf } from '../hooks/views/frames'
+
+const header = (): string => {
+ const grid = bannerPicture('demo', 100, 0)
+
+ return Array.from({ length: grid.columns }, (_, x) => String.fromCodePoint(grid.cells[x * 3] || 32)).join('')
+}
describe('console version', () => {
it('matches the plugin manifest, so the header shows the build that is running', () => {
@@ -16,3 +27,53 @@ describe('console version', () => {
expect(CONSOLE_VERSION).toBe(manifest.version)
})
})
+
+describe('build id', () => {
+ afterEach(() => setBuild(''))
+
+ it('accepts a short revision, with -dirty for uncommitted edits, and nothing else', () => {
+ expect(buildOf('2dc45ae\n')).toBe('2dc45ae')
+ expect(buildOf('2dc45ae-dirty')).toBe('2dc45ae-dirty')
+ expect(buildOf('')).toBe('')
+ expect(buildOf('fatal: not a git repository')).toBe('')
+ expect(buildOf('\u001b[31m2dc45ae')).toBe('')
+ expect(buildOf('2dc45ae-dirty; rm -rf')).toBe('')
+ expect(buildOf('XYZ')).toBe('')
+ expect(buildOf('a'.repeat(41))).toBe('')
+ })
+
+ it('takes a folder as ours only when it is plugins/ruflo-console in its repository, so an installed copy inside another repo shows no commit', () => {
+ expect(isOurCheckout('plugins/ruflo-console/\n')).toBe(true)
+ expect(isOurCheckout('plugins/ruflo-console')).toBe(true)
+ expect(isOurCheckout('\n')).toBe(false)
+ expect(isOurCheckout('.claude/plugins/cache/ruflo/ruflo-console/0.25.0/\n')).toBe(false)
+ expect(isOurCheckout('plugins/ruflo-console-evil/')).toBe(false)
+ })
+
+ it('the plain look, which has no banner, shows the version and the build on its own header too', () => {
+ const plain = (): string => {
+ const state = newState({ look: 'plain' } as never)
+
+ state.view = 'menu'
+
+ const grid = picturesOf(state, 90, 0, 5).get('header') as ReturnType<typeof bannerPicture>
+
+ return Array.from({ length: grid.columns }, (_, x) => String.fromCodePoint(grid.cells[x * 3] || 32)).join('')
+ }
+
+ expect(plain()).toContain(`◆ ruflo v${CONSOLE_VERSION} ·`)
+ expect(plain()).not.toContain('2dc45ae')
+
+ setBuild('2dc45ae')
+ expect(plain()).toContain(`◆ ruflo v${CONSOLE_VERSION} · 2dc45ae ·`)
+ })
+
+ it('shows on the header after the version when known, and not at all when not', () => {
+ expect(header()).toContain(`v${CONSOLE_VERSION}`)
+ expect(header()).not.toContain('·')
+
+ setBuild('2dc45ae-dirty')
+ expect(getBuild()).toBe('2dc45ae-dirty')
+ expect(header()).toContain(`v${CONSOLE_VERSION} · 2dc45ae-dirty`)
+ })
+})
diff --git a/v3/docs/adr/ADR-426-console-self-check-boot-report-and-visible-runs.md b/v3/docs/adr/ADR-426-console-self-check-boot-report-and-visible-runs.md
index 604a3070bf..55453881ba 100644
--- a/v3/docs/adr/ADR-426-console-self-check-boot-report-and-visible-runs.md
+++ b/v3/docs/adr/ADR-426-console-self-check-boot-report-and-visible-runs.md
@@ -56,3 +56,12 @@ It does not run the CLI, so a command that is well-formed but names a verb the i
- `tests/self-check.spec.ts` (12): the real registries pass; every boot area is checked, in boot order, and every area names a real page, so no `[ OK ]` goes unchecked; the four registry areas have their commands counted; and a broken entry fails each way: a text verb that builds a command from an empty field, one that lets `-` through, one that refuses every input, an empty argv part, a command with no reader, a Dev Tools row no input can run, one with no input field that cannot run empty, an n/a with no reason, a lab verb that cannot run and does not say why, one with nothing to run or type, a duplicate id, and a page that is missing, has no key, or has no Ask row. A check that cannot fail would prove nothing, so these are the point.
- `tests/diagrams.spec.ts`: with results the log shows `[ OK ]` for a passed area and `[FAIL]` with its problem for a failed one, READY counts what was verified and fails when any did, and an area still starting shows `[ .. ]`.
- The console suite passes 365 tests. 22 files cannot load the `claude-code/testing` host package here, each failing only on that import; they run in CI (ADR 413). The row text, the dimmed button and the send button are in those, so they are not yet exercised.
+
+## 6. Amendment: which build is running, and every look
+
+- **The version cannot say which build.** It is the same across every commit of a release, so a session on a stale copy and one on the latest both read `v0.26.0`. The header now adds the git revision, `v0.26.0 · 2dc45ae`, with `-dirty` when the tree has uncommitted edits. `hooks/build.ts` (a leaf) holds it; `register.ts` reads it once at session start with two read-only `git` calls and sets it only when the plugin folder is `plugins/ruflo-console` of the repository git reports, so an installed copy that sits inside some other repository never shows that repository's commit. The text is validated as a short hex revision, since it is drawn on the screen.
+- **The plain look has no banner.** Its one-line header (`◆ ruflo · project`) now carries the version and the build too, widened from 40 to 64 columns.
+- **The boot screen is not in every look.** The plain look draws none, and a BBS look can turn the boot off, so a failed self-check would have been silent there. A failed area is now also an Overview alert (`self-check: Security failed — …`), drawn before any project is read.
+- **A redraw timer must respect `fps: 0`.** The guidance section's ticker (it keeps the spinner turning before the first words arrive) redrew four times a second whatever the setting. It now redraws only when `fps` is above zero and the pane is open; the section still updates as words arrive.
+
+There is no mode called "lite" in the console. What exists is the plain look, `fps: 0`, narrow and compact panes, and surfaces without a text field; the changes above were checked against those, not against a lite mode.
diff --git a/v3/docs/adr/ADR-428-console-update-check-and-auto-update.md b/v3/docs/adr/ADR-428-console-update-check-and-auto-update.md
new file mode 100644
index 0000000000..8eb9a4fdd4
--- /dev/null
+++ b/v3/docs/adr/ADR-428-console-update-check-and-auto-update.md
@@ -0,0 +1,60 @@
+# ADR 428: The console offers a newly published version at load, and can keep itself up to date
+
+Status: Accepted (ships in ruflo-console 0.26.0)
+
+Date: 2026 10 03
+
+Decision owner: Ruflo maintainers
+
+Scope: `plugins/ruflo-console`: `hooks/updates.ts` (new, pure), `hooks/update-flow.ts` (new), `hooks/host.ts` (`fetchText`, `askChoice`, `toast`), `hooks/register.ts`, `hooks/bindings.ts` (`updates`, `checkUpdates`), `hooks/views/settings.ts` (an Updates row), `hooks/state.ts` (`updates`, `updateNote`, `updateAvailable`), `.claude-plugin/plugin.json` (the description), `tests/updates.spec.ts` (new).
+
+Extends: ADR 407 (the cockpit), ADR 426 (the build id: a development checkout is recognised by it).
+
+## 1. Context
+
+The console ships through the `ruflo` marketplace (GitHub `ruvnet/ruflo`). A person gets a new version only by remembering `claude plugin marketplace update` and `claude plugin update`, then restarting, and nothing says a version has been published. The result is people on stale builds reporting things already fixed. The owner asked for the console to say so at load, with a yes, and for an "always auto-update".
+
+## 2. Decision
+
+### 2.1 What it checks, and when
+At session start, a couple of seconds after the screen has settled and once the build is known, the console reads the published `plugins/ruflo-console/.claude-plugin/plugin.json` on `main` (one small request through the host's `$.http.fetch`, so an administrator's policy can refuse it) and compares its `version` with the one running. It does so at most once a day (the time is kept in the plugin's store, shared by sessions), and never in a non-interactive `-p` run (nobody to ask), nor in a development checkout (a session loaded from a git worktree updates with git; the build id of ADR 426 says which).
+
+It accepts the manifest only if its `name` is `ruflo-console` and its `version` is a plain `major.minor.patch`, and offers only a **strictly newer** one: never the same, an older one, or a pre-release.
+
+### 2.2 The offer
+Claude Code's own choice dialog (`$.ui.ask`): **Update now**, **Always auto-update**, **Not now**. The question says what it will run (`claude plugin marketplace update`, then `claude plugin update`), that it takes effect after a restart or `/reload-plugins`, and what "Always" means: every new minor or patch version published to `github.com/ruvnet/ruflo`, installed without asking, a new major version still asking, and where to turn it off. A new **major** version is offered without an Always choice. Dismissing the dialog, or typing under Other, installs nothing.
+
+### 2.3 "Always auto-update"
+A mode, `ask` (the default), `auto` or `off`, kept in the plugin's store and set in **Settings → Updates**, where a **check for an update now** button also lives (it ignores the daily limit and an off setting, because the person asked, but it still asks before installing, and still skips a development checkout). In `auto`, a minor or patch version is installed without a question, with a toast before and after; a major version asks.
+
+This departs from a rule the console keeps elsewhere: an action that reaches the network never offers "Always allow" (as the Settings page says of its remembered actions). It is a deliberate, requested exception, kept narrow: strictly newer only; never across a major version; only from the marketplace the plugin was installed from; installed by Claude Code, not by this code; one setting turns it off.
+
+### 2.4 The install is Claude Code's
+The console never downloads or runs the new code. It runs `claude plugin list --json` (to find the scope the plugin is installed in), `claude plugin marketplace update ruflo`, then `claude plugin update ruflo-console@ruflo --scope <that scope>`, and then lists again. It **never passes `-y` or `--accept-command`**: if a marketplace declares a command, Claude Code refuses to run it unattended and asks a person; the console reports that and gives the command to run by hand. It does not call the update installed unless the list afterwards shows the new version; otherwise it says what the list shows and to check `/plugin`.
+
+### 2.5 Several sessions
+A person runs many sessions. The check time is shared, so a second session starting soon after the first does not ask again; a session that begins installing records the time, and others hold off for ten minutes; a version that has been installed and is waiting for a restart is not offered again. The store is not atomic, so this narrows a race, it does not remove one.
+
+## 3. Alternatives considered
+
+- **Check by running `claude plugin marketplace update` first.** Rejected: it pulls the whole `ruvnet/ruflo` repository to learn a version number, every day, in every session. One small file is the same information.
+- **Fetch with `curl`.** Rejected: not on every machine, and it would be the plugin's own network, outside the host's policy.
+- **Install by fetching and unpacking the new files ourselves.** Rejected outright: it would bypass Claude Code's trust model for plugin code, which is the thing a marketplace install gives.
+- **`auto` as the default.** Rejected: the person chooses it, once, with the words that say what it does.
+- **Check off by default.** The owner asked for the offer at load, so the default is `ask`. This changes what the plugin's description used to say ("no network by default"); the description now names the one request and where to turn it off.
+
+## 4. What this does not prove
+
+The pure rules and the whole flow are tested with fakes (no host, no network): when it looks, what it asks, what it runs, what it refuses. Not tested, because it cannot be here:
+
+- **Whether the choice dialog can be shown a couple of seconds after session start.** If the host refuses it, the call rejects and the console treats that as "not now": no update, no error. The first live run should confirm the question appears.
+- **Whether `claude plugin update` accepts `--scope` as written and whether `claude plugin list --json` carries the version for a plugin installed from this marketplace on every version of Claude Code.** The flow reads the list back and says so when it does not match, rather than assuming.
+- **A light theme.** Not related to updates; see ADR 429.
+
+## 5. Tests
+
+`tests/updates.spec.ts` (33):
+
+- **Rules:** a version is only `major.minor.patch`; a bump is patch, minor or major and never a downgrade, a pre-release or garbage; the manifest is ours or null; the daily gate, including a stored time in the future; another session updating holds off for ten minutes and no longer; `off` does nothing, `auto` installs minor and patch but asks for a major, and anything not exactly `auto` or `off` is `ask`; the question ends in a question mark, names the repository and what Always means, and has no Always for a major version; the installed list prefers the user scope, then an enabled entry, and ignores other plugins.
+- **Flow:** does not even look when off, non-interactive, or a development checkout; at most once a day; skips a version already installed; fails quietly, and tries again next time, when GitHub cannot be reached, hangs (on the host's clock, not `setTimeout`), or sends something that is not our manifest; never throws, even when the store does; Not now, a dismissed dialog and typed text install nothing; Update now runs exactly the list, the marketplace update, the plugin update in the installed scope, and the list; Always turns auto on and installs; auto installs without asking and toasts; auto still asks for a major version, and "Always" cannot be taken for one; "check now" ignores the gate and off but asks and skips a development checkout.
+- **What it will not do:** no `-y`, `--yes` or `--accept-command` in any run (checked by adding `-y` and watching two tests fail, then restoring it); Claude Code's own confirmation is reported with the command to run; it does not say installed when the list still shows the old version; it has nothing to update, and says why, when the plugin is not installed from the marketplace (a `--plugin-dir` session); it stops, saying why, when the marketplace will not update; and it always releases the other sessions, whether the install worked or not.