Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Self-upgrade decision + state foundation (v0.42 self-upgrading-gbrain wave).
*
* Mirrors gstack's invocation-riding update mechanism for gbrain: a throttled
* check that rides every `gbrain` invocation (CLI / MCP), emits a marker, and
* either prompts (mode=notify) or silently upgrades (mode=auto, opt-in). A
* second silent channel lives in the autopilot daemon. Both channels share the
* cache + snooze + lock state defined here so they can never double-upgrade.
*
* This module is the PURE + state foundation:
* - `decideSelfUpgrade()` — pure decision over already-resolved inputs.
* - cache helpers — one file per release channel stamped with its evidence
* policy; atomic temp+rename writes, strict parse, mtime-TTL.
* - snooze helpers — per channel, time-based, escalating 24h/48h/7d.
* - `formatMarker` / `parseMarker` — ONE marker grammar shared by the CLI
* emit, the MCP emit, and the agent skill (no drift; forged markers
* rejected via the version regex).
*
* Hot-path contract: the CLI startup read is cache-read-only (statSync + read,
* sub-ms). Network refresh is detached + single-flighted; it NEVER blocks a
* command. The version string is regex-validated AND monotonic-checked before
* it reaches the agent's context (a malicious brain page / MCP response can
* neither forge a "downgrade-as-upgrade" nor change the action — the action is
* always the hardcoded `gbrain upgrade` / `gbrain self-upgrade`).
*
* NO DB. The hot path runs before `connectEngine()` and thin clients have no
* local DB, so all state is file-based under `~/.gbrain/` (honors GBRAIN_HOME).
*/
import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { gbrainPath, isConfigTruthy, loadConfigFileOnly } from './config.ts';
import { isValidTimeZone } from './cycle/cycle-date.ts';
import { isValidConfig as isValidQuietHoursWindow } from './minions/quiet-hours.ts';
import { evaluateBunFloor, type HostBun, type TargetFloor } from './bun-floor.ts';
import { acquirePackLock, type PackLockOpts } from './schema-pack/pack-lock.ts';
import { isNewerVersion, isValidVersionString, parseSemver, semverGt, semverLte } from './semver.ts';
// ── Constants ───────────────────────────────────────────────────────────────
/** Cache freshness: short when up-to-date (detect releases fast), long when an
* upgrade is already pending (don't re-fetch on every invocation). Mirrors
* gstack (60min / 12h). */
export const CACHE_TTL_UP_TO_DATE_MS = 60 * 60 * 1000;
export const CACHE_TTL_UPGRADE_AVAILABLE_MS = 12 * 60 * 60 * 1000;
/** Auto channel only checks once per this interval. */
export const AUTO_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
/** Escalating snooze durations by level (gstack-style). Level >=3 caps at 7d. */
export const SNOOZE_DURATIONS_MS = [
24 * 60 * 60 * 1000, // level 1 → 24h
48 * 60 * 60 * 1000, // level 2 → 48h
7 * 24 * 60 * 60 * 1000, // level 3+ → 7d
] as const;
// ── Types ─────────────────────────────────────────────────────────────────
export type SelfUpgradeMode = 'auto' | 'notify' | 'off';
/**
* The release line an install follows (GBRA-224 W1). `stable` (the default) is the newest release a maintainer
* promoted after its gates passed on the exact tree, published with an evidence record (core/stable-channel.ts);
* `alpha` is every published release (the `latest-stable` tag release.yml advances). `latest` is accepted
* everywhere as an alias for alpha. Precedence: `--channel`, then GBRAIN_RELEASE_CHANNEL, then
* `self_upgrade.channel` (file plane), then stable.
*/
export type ReleaseChannel = 'stable' | 'alpha';
export const RELEASE_CHANNELS: readonly ReleaseChannel[] = ['stable', 'alpha'];
export const DEFAULT_RELEASE_CHANNEL: ReleaseChannel = 'stable';
export const RELEASE_CHANNEL_ENV = 'GBRAIN_RELEASE_CHANNEL';
export const VALID_CHANNELS_TEXT = 'stable or alpha (latest is an alias for alpha)';
export function normalizeChannel(raw: unknown): ReleaseChannel | null {
if (typeof raw !== 'string') return null;
if (raw === 'stable') return 'stable';
return raw === 'alpha' || raw === 'latest' ? 'alpha' : null;
}
export type ChannelSource = 'flag' | 'env' | 'config' | 'default';
export type ChannelResolution =
| { ok: true; channel: ReleaseChannel; source: ChannelSource }
| { ok: false; source: Exclude<ChannelSource, 'default'>; raw: string };
/**
* The effective channel and where it came from. `flag` is the raw `--channel` value (null when absent, '' when the
* flag had no value). The first source present decides; an invalid value there is an error, never a fallthrough.
*/
export function resolveReleaseChannel(
cfg: { self_upgrade?: { channel?: string } } | null | undefined,
flag: string | null = null,
env: string | undefined = process.env[RELEASE_CHANNEL_ENV],
): ChannelResolution {
const sources: Array<[Exclude<ChannelSource, 'default'>, string | null | undefined]> = [
['flag', flag],
['env', env === '' ? undefined : env],
['config', cfg?.self_upgrade?.channel],
];
for (const [source, raw] of sources) {
if (raw === null || raw === undefined) continue;
const channel = normalizeChannel(raw);
return channel ? { ok: true, channel, source } : { ok: false, source, raw: String(raw) };
}
return { ok: true, channel: DEFAULT_RELEASE_CHANNEL, source: 'default' };
}
/** The hot-path channel (env and file-plane config, no flag); null when the value there is invalid. */
export function currentReleaseChannel(): ReleaseChannel | null {
const res = resolveReleaseChannel(loadConfigFileOnly());
return res.ok ? res.channel : null;
}
/** The command that moves this install to `target`, rendered against what currently decides the channel. */
export function channelSwitchCommand(target: ReleaseChannel, res: ChannelResolution): string {
if (res.source === 'flag') return `gbrain upgrade --channel ${target}`;
if (res.source === 'env') return `${RELEASE_CHANNEL_ENV}=${target} (it overrides self_upgrade.channel), or unset ${RELEASE_CHANNEL_ENV} and run gbrain config set self_upgrade.channel ${target}`;
return `gbrain config set self_upgrade.channel ${target}`;
}
/** A usage-error sentence for an invalid channel value. */
export function invalidChannelMessage(res: Extract<ChannelResolution, { ok: false }>): string {
const where = res.source === 'flag' ? '--channel' : res.source === 'env' ? RELEASE_CHANNEL_ENV : 'self_upgrade.channel';
return `${where} is '${res.raw}', which is not a release channel; use ${VALID_CHANNELS_TEXT}.`;
}
/**
* The evidence policy a cached stable answer was validated under. A record whose version is at or above
* MATRIX_REQUIRED_FROM must carry `matrix_run` as well as `soak_run`; null until the upgrade matrix (W2) ships, so
* every generation-1 record (soak evidence only) stays valid. Changing either changes the policy id, which
* invalidates cached stable answers.
*/
export const MATRIX_REQUIRED_FROM: string | null = null;
export const STABLE_EVIDENCE_POLICY = `stable-record-v1;matrix-from=${MATRIX_REQUIRED_FROM ?? 'none'}`;
export const ALPHA_EVIDENCE_POLICY = 'alpha-version-file-v1';
export function evidencePolicyFor(channel: ReleaseChannel): string {
return channel === 'stable' ? STABLE_EVIDENCE_POLICY : ALPHA_EVIDENCE_POLICY;
}
export type SelfUpgradeChannel = 'invocation' | 'autopilot';
/**
* The decision outcome. `apply` = silently run the upgrade (autopilot/auto
* only). `notify` = surface the marker / 4-option prompt. Everything else is a
* no-op with a named reason (for the audit trail + doctor).
*/
export type SelfUpgradeAction =
| 'off'
| 'not_behind'
| 'downgrade_or_yanked'
| 'known_bad'
| 'throttled'
| 'busy'
| 'outside_quiet_hours'
| 'unsupported_install'
| 'unsupported_runtime'
| 'notify'
| 'apply';
export interface SelfUpgradeDecision {
action: SelfUpgradeAction;
reason: string;
current: string;
latest: string | null;
}
export interface DecideSelfUpgradeInputs {
mode: SelfUpgradeMode;
currentVersion: string;
/** Latest known version (from cache/marker). null when unknown → fail-open. */
latestVersion: string | null;
/** Versions that failed a prior auto-upgrade (never auto-retried). */
failedVersions: string[];
channel: SelfUpgradeChannel;
// autopilot-channel gates (ignored for invocation):
idle?: boolean;
inQuietHours?: boolean;
canSelfUpdate?: boolean;
/** True when the last auto-check was < AUTO_CHECK_INTERVAL_MS ago. */
throttledByInterval?: boolean;
// invocation-channel gate (ignored for autopilot):
/** True when an unexpired snooze covers `latestVersion`. */
snoozed?: boolean;
}
export type MarkerKind = 'up_to_date' | 'upgrade_available';
export interface UpdateMarker {
kind: MarkerKind;
current: string;
/** Present only when kind === 'upgrade_available'. */
latest?: string;
}
export interface SnoozeRecord {
version: string;
level: number;
/** Epoch ms when the snooze was written. */
ts: number;
/** Epoch ms when it ends. */
until: number;
}
// ── Pure decision ───────────────────────────────────────────────────────────
/**
* Decide what to do about a possible upgrade. Pure: all I/O-derived inputs are
* resolved by the caller. The version comparison is monotonic — we only ever
* act when `latest` is a real release strictly greater than `current`,
* so a downgrade / yanked / prerelease-local-build can never trigger an upgrade.
*/
export function decideSelfUpgrade(inp: DecideSelfUpgradeInputs): SelfUpgradeDecision {
const base = { current: inp.currentVersion, latest: inp.latestVersion };
if (inp.mode === 'off') {
return { action: 'off', reason: 'self_upgrade.mode=off', ...base };
}
if (!inp.latestVersion || !isValidVersionString(inp.latestVersion)) {
return { action: 'not_behind', reason: 'latest version unknown or invalid', ...base };
}
const cur = parseSemver(inp.currentVersion);
const lat = parseSemver(inp.latestVersion);
if (!cur || !lat) {
return { action: 'not_behind', reason: 'unparseable version', ...base };
}
if (semverLte(lat, cur)) {
// Equal → up to date; strictly-less → a downgrade / yanked release. Never act.
if (semverGt(cur, lat)) {
return { action: 'downgrade_or_yanked', reason: `latest ${inp.latestVersion} < current ${inp.currentVersion}`, ...base };
}
return { action: 'not_behind', reason: 'already current', ...base };
}
if (inp.failedVersions.includes(inp.latestVersion)) {
return { action: 'known_bad', reason: `${inp.latestVersion} previously failed; not retrying`, ...base };
}
// Genuinely behind by a newer release and not known-bad.
if (inp.channel === 'invocation') {
if (inp.snoozed) {
return { action: 'throttled', reason: 'snoozed for this version', ...base };
}
return { action: 'notify', reason: `update available: ${inp.currentVersion} -> ${inp.latestVersion}`, ...base };
}
// autopilot channel (silent auto)
if (inp.throttledByInterval) {
return { action: 'throttled', reason: 'auto-check ran within 24h', ...base };
}
if (!inp.idle) {
return { action: 'busy', reason: 'brain not idle', ...base };
}
if (!inp.inQuietHours) {
return { action: 'outside_quiet_hours', reason: 'outside quiet hours', ...base };
}
if (!inp.canSelfUpdate) {
return { action: 'unsupported_install', reason: 'install method cannot self-update', ...base };
}
return { action: 'apply', reason: `auto-upgrading ${inp.currentVersion} -> ${inp.latestVersion}`, ...base };
}
/**
* Runtime gate for an `apply` on an install that runs the target on the host's
* Bun (every method but `binary`, which carries its own runtime). Holds the
* upgrade when the target's `engines.bun` floor is above the host's Bun, or
* when either could not be read: once swapped, every command refuses at
* startup (the relaunched daemon included, before it can reconcile the
* breadcrumb) and an unattended host has nothing that upgrades Bun (#5855).
* The target is NOT recorded known-bad, so the first tick after the cause
* clears applies it. #6828: the version the install would actually get (a
* bun-link clone follows master, a moving tag can pass the checked version)
* is also checked against `failedVersions`, so a release recorded known-bad
* under its installed version is not reinstalled while the check names
* another one. Pure.
*/
export function gateOnTargetRuntime(
decision: SelfUpgradeDecision,
target: TargetFloor,
host: HostBun | null,
failedVersions: readonly string[] = [],
): SelfUpgradeDecision {
if (decision.action !== 'apply') return decision;
if (target.version && target.version !== decision.latest && failedVersions.includes(target.version)) {
return { ...decision, action: 'known_bad', reason: `the install would get ${target.version}, which previously failed; not retrying` };
}
const verdict = evaluateBunFloor(target, host, decision.latest);
if (verdict.ok) return decision;
const retry = verdict.kind === 'unreadable' ? ' The next quiet-hours tick retries.' : '';
return { ...decision, action: 'unsupported_runtime', reason: `${verdict.auditReason}${retry}` };
}
/**
* Whether this install method + platform/arch can apply an upgrade unattended.
* `bun` / `bun-link` delegate to their package managers; `binary`
* self-updates via atomic rename ONLY where a release asset is published —
* today that's darwin-arm64 and linux-x64 (see `.github/workflows/release.yml`).
* Other binary platform/arch combos (darwin-x64, linux-arm64, win32) have no
* asset and stay notify-only. `unknown` cannot self-update.
*/
export function canSelfUpdate(
installMethod: string,
platform: NodeJS.Platform = process.platform,
arch: NodeJS.Architecture = process.arch,
): boolean {
switch (installMethod) {
case 'bun':
case 'bun-link':
return true;
case 'binary':
return (platform === 'darwin' && arch === 'arm64') || (platform === 'linux' && arch === 'x64');
default:
return false;
}
}
// ── Marker grammar (shared by CLI + MCP + agent skill) ───────────────────────
/** Serialize a marker line. The cache file content IS this string. */
export function formatMarker(m: UpdateMarker): string {
if (m.kind === 'upgrade_available' && m.latest) {
return `UPGRADE_AVAILABLE ${m.current} ${m.latest}`;
}
return `UP_TO_DATE ${m.current}`;
}
/**
* Parse a marker line. Strict: both versions must pass the version regex, or we
* return null. This is the forged-marker guard — a malicious string can't smuggle
* a non-version token (or a command) into the agent's context as an "upgrade".
*/
export function parseMarker(line: string): UpdateMarker | null {
const parts = line.trim().split(/\s+/);
if (parts[0] === 'UP_TO_DATE' && parts.length === 2 && isValidVersionString(parts[1])) {
return { kind: 'up_to_date', current: parts[1] };
}
if (
parts[0] === 'UPGRADE_AVAILABLE' &&
parts.length === 3 &&
isValidVersionString(parts[1]) &&
isValidVersionString(parts[2])
) {
return { kind: 'upgrade_available', current: parts[1], latest: parts[2] };
}
return null;
}
// ── State file paths ────────────────────────────────────────────────────────
/** Files from before the cache was partitioned by channel (GBRA-224): never read, removed on clear. */
const LEGACY_CACHE_FILE = 'last-update-check';
const LEGACY_SNOOZE_FILE = 'update-snoozed';
/** The update-check cache for one channel (default: the hot-path channel; stable when that is invalid). */
export function updateCachePath(channel: ReleaseChannel = currentReleaseChannel() ?? DEFAULT_RELEASE_CHANNEL): string {
return gbrainPath(`update-check.${channel}.json`);
}
/** The "Not now" snooze for one channel. */
export function snoozePath(channel: ReleaseChannel = currentReleaseChannel() ?? DEFAULT_RELEASE_CHANNEL): string {
return gbrainPath(`update-snoozed.${channel}.json`);
}
export function justUpgradedPath(): string {
return gbrainPath('just-upgraded-from');
}
/**
* Record the version we just upgraded FROM, so the next `gbrain` invocation's
* startup hook can print the one-time `JUST_UPGRADED <from> <to>` confirmation
* and then delete the breadcrumb. Best-effort: a failed write just means no
* confirmation line. Atomic so a concurrent read never sees a torn file.
*/
export function writeJustUpgraded(fromVersion: string): void {
try {
atomicWrite(justUpgradedPath(), fromVersion + '\n');
} catch {
/* best-effort confirmation */
}
}
/** Directory for the self-upgrade + refresh single-flight locks. */
export function locksDir(): string {
return gbrainPath('.locks');
}
// ── Cache (untrusted local state: atomic write, strict parse, mtime-TTL) ─────
/** A stable lookup that failed, kept so doctor and --check-only can report it without a network call. */
export interface StableLookupError {
code: 'stable_missing' | 'stable_invalid' | 'stable_unreadable';
cause: string;
}
/**
* One channel's cached answer. Partitioned by channel (one file each) and stamped with the evidence policy it was
* validated under, so a channel switch, a default flip or a policy change never reads another partition's answer.
* `latest` is the channel's release (on stable, the evidence record's version, which can be below the running build);
* `knownBad` is the record's withdrawn list; `error` is set when the last stable lookup failed.
*/
export interface CacheEntry {
marker: UpdateMarker | null;
mtimeMs: number;
channel: ReleaseChannel;
policy: string;
checkedAt: number;
latest: string | null;
knownBad: string[];
error: StableLookupError | null;
}
export interface CacheWriteOptions {
channel?: ReleaseChannel;
/** The channel's release when it differs from the marker's (a stable record below the running build). */
latest?: string | null;
knownBad?: readonly string[];
error?: StableLookupError | null;
/** When the refresh that produced this answer started; an older answer never overwrites a newer one. */
checkedAt?: number;
}
const STABLE_CODES = new Set(['stable_missing', 'stable_invalid', 'stable_unreadable']);
/** How far ahead of this clock a stored check time may be (NTP skew); further ahead means the clock moved back since the write, so it is ignored (#8795). The file's mtime is not checked: a network home's file server sets it by its own clock. */
const CACHE_FUTURE_SKEW_MS = 5 * 60 * 1000;
let _tmpCounter = 0;
function atomicWrite(path: string, content: string): void {
const dir = dirname(path);
mkdirSync(dir, { recursive: true });
const tmp = `${path}.tmp.${process.pid}.${_tmpCounter++}`;
const fd = openSync(tmp, 'w', 0o600);
try {
writeFileSync(fd, content);
} finally {
closeSync(fd);
}
renameSync(tmp, path);
}
function unlinkQuiet(path: string): void {
try {
unlinkSync(path);
} catch {
/* already gone */
}
}
/**
* Read + strict-parse one channel's cache. Null on missing, corrupt, another channel's or another evidence policy's
* entry (a legacy unpartitioned file is never read).
*/
export function readUpdateCache(channel: ReleaseChannel | null = currentReleaseChannel()): CacheEntry | null {
if (!channel) return null;
const path = updateCachePath(channel);
let raw: Record<string, unknown>;
let mtimeMs: number;
try {
raw = JSON.parse(readFileSync(path, 'utf8'));
mtimeMs = statSync(path).mtimeMs;
} catch {
return null;
}
if (!raw || typeof raw !== 'object' || raw.schema !== 2) return null;
if (raw.channel !== channel || raw.policy !== evidencePolicyFor(channel)) return null;
const marker = raw.marker === null ? null : parseMarker(String(raw.marker ?? ''));
if (raw.marker !== null && !marker) return null;
const latest = typeof raw.latest === 'string' && isValidVersionString(raw.latest) ? raw.latest : null;
const knownBad = Array.isArray(raw.known_bad) ? raw.known_bad.filter((v): v is string => typeof v === 'string' && isValidVersionString(v)) : [];
const e = raw.error as { code?: unknown; cause?: unknown } | null | undefined;
const error = e && typeof e === 'object' && typeof e.code === 'string' && STABLE_CODES.has(e.code)
? { code: e.code as StableLookupError['code'], cause: typeof e.cause === 'string' ? e.cause.slice(0, 300) : '' }
: null;
if (!marker && !error) return null;
const checkedAt = typeof raw.checked_at === 'number' && Number.isFinite(raw.checked_at) ? raw.checked_at : mtimeMs;
return { marker, mtimeMs, channel, policy: raw.policy as string, checkedAt, latest: latest ?? marker?.latest ?? null, knownBad, error };
}
/**
* Atomically write one channel's cache (0600). A refresh that started before the stored answer's refresh never
* overwrites it (reversed completion), unless the stored check time is more than CACHE_FUTURE_SKEW_MS ahead of this clock.
* Best-effort: throws only on truly unexpected fs errors.
*/
export function writeUpdateCache(marker: UpdateMarker | null, opts: CacheWriteOptions = {}): void {
const channel = opts.channel ?? currentReleaseChannel() ?? DEFAULT_RELEASE_CHANNEL;
const now = Date.now();
const checkedAt = opts.checkedAt ?? now;
const prior = readUpdateCache(channel);
if (prior && prior.checkedAt > checkedAt && prior.checkedAt <= now + CACHE_FUTURE_SKEW_MS) return;
atomicWrite(updateCachePath(channel), JSON.stringify({
schema: 2,
channel,
policy: evidencePolicyFor(channel),
checked_at: checkedAt,
marker: marker ? formatMarker(marker) : null,
latest: opts.latest === undefined ? marker?.latest ?? null : opts.latest,
known_bad: [...(opts.knownBad ?? [])],
error: opts.error ?? null,
}) + '\n');
unlinkQuiet(gbrainPath(LEGACY_CACHE_FILE));
}
/** Clear every channel's cache (e.g. after a successful upgrade) so the next run re-checks. */
export function clearUpdateCache(): void {
for (const channel of RELEASE_CHANNELS) unlinkQuiet(updateCachePath(channel));
unlinkQuiet(gbrainPath(LEGACY_CACHE_FILE));
}
export function isCacheFresh(entry: CacheEntry, now: number): boolean {
const ttl = entry.marker?.kind === 'upgrade_available' && !entry.error ? CACHE_TTL_UPGRADE_AVAILABLE_MS : CACHE_TTL_UP_TO_DATE_MS;
return entry.checkedAt <= now + CACHE_FUTURE_SKEW_MS && now - entry.mtimeMs < ttl;
}
/**
* The release a channel offers this build: its release when strictly newer, or, on stable, the current stable when
* the running version is on the record's known_bad list (the one move below the running build the channel makes,
* because the record says so). Null otherwise. Pure.
*/
export function offeredVersion(runningVersion: string, latest: string | null, knownBad: readonly string[]): string | null {
if (!latest || !isValidVersionString(latest)) return null;
if (isNewerVersion(runningVersion, latest)) return latest;
return knownBad.includes(runningVersion) && latest !== runningVersion ? latest : null;
}
/**
* The one shared "is an upgrade actually pending for THIS binary?" predicate.
* Returns the offered version (offeredVersion) when the effective channel's cache is present and fresh — else
* null. The running-version comparison is the load-bearing part: the cache
* records the version of whatever binary WROTE it (an older gbrain on PATH can
* write it via the detached refresh), so consumers must never trust
* `marker.current` to describe themselves. Every upgrade-nag surface (CLI
* startup marker, doctor, advisor, get_brain_identity) routes through here so
* the suppression rule cannot drift per-surface. Never throws.
*/
export function pendingUpgradeVersion(runningVersion: string, now: number = Date.now(), channel: ReleaseChannel | null = currentReleaseChannel()): string | null {
try {
const entry = readUpdateCache(channel);
if (!entry || !isCacheFresh(entry, now)) return null;
if (entry.error?.code === 'stable_missing' || entry.error?.code === 'stable_invalid') return null;
return offeredVersion(runningVersion, entry.latest, entry.knownBad);
} catch {
return null;
}
}
// ── Snooze (interactive prompting only; never overrides mode=off) ────────────
/**
* Read one channel's snooze. A snooze is time-based: "Not now" holds until `until` whatever the channel ships
* meanwhile; `version` is what was offered when it was written (a rollback below it ends the snooze).
*/
export function readSnooze(channel: ReleaseChannel = currentReleaseChannel() ?? DEFAULT_RELEASE_CHANNEL): SnoozeRecord | null {
let raw: Record<string, unknown>;
try {
raw = JSON.parse(readFileSync(snoozePath(channel), 'utf8'));
} catch {
return null;
}
const { version, level, ts, until } = raw ?? {};
if (typeof version !== 'string' || !isValidVersionString(version)) return null;
if (!Number.isInteger(level) || (level as number) < 1 || !Number.isFinite(ts) || !Number.isFinite(until)) return null;
return { version, level: level as number, ts: ts as number, until: until as number };
}
/** Snooze duration for a level (1-indexed; >=3 caps at 7d). */
export function snoozeDurationMs(level: number): number {
const idx = Math.min(Math.max(level, 1), SNOOZE_DURATIONS_MS.length) - 1;
return SNOOZE_DURATIONS_MS[idx];
}
/**
* True iff an unexpired snooze covers an offer of `offered`. Newer releases never end it (it is time-based); an
* offer below the snoozed version (a stable rollback) does.
*/
export function isSnoozeActive(snooze: SnoozeRecord | null, offered: string, now: number): boolean {
if (!snooze || now >= snooze.until) return false;
return !isNewerVersion(offered, snooze.version);
}
/**
* Whether the channel's snooze holds back an offer of `offered`. A snooze the offer rolled back below is cleared,
* so the rolled-back release is offered at once.
*/
export function snoozeHolds(offered: string, now: number, channel: ReleaseChannel = currentReleaseChannel() ?? DEFAULT_RELEASE_CHANNEL): boolean {
const snooze = readSnooze(channel);
if (snooze && isNewerVersion(offered, snooze.version)) {
clearSnooze(channel);
return false;
}
return isSnoozeActive(snooze, offered, now);
}
/**
* Record (or escalate) "Not now" on a channel: level 1 (24 h), then 48 h, then 7 d for each later "Not now" until an
* upgrade clears it. Written atomically. Returns the new record.
*/
export function writeSnooze(offered: string, now: number, channel: ReleaseChannel = currentReleaseChannel() ?? DEFAULT_RELEASE_CHANNEL): SnoozeRecord {
const existing = readSnooze(channel);
const level = existing ? Math.min(existing.level + 1, SNOOZE_DURATIONS_MS.length) : 1;
const record = { version: offered, level, ts: now, until: now + snoozeDurationMs(level) };
atomicWrite(snoozePath(channel), JSON.stringify(record) + '\n');
return record;
}
/** Clear one channel's snooze, or every channel's (after an upgrade). */
export function clearSnooze(channel?: ReleaseChannel): void {
for (const c of channel ? [channel] : RELEASE_CHANNELS) unlinkQuiet(snoozePath(c));
if (!channel) unlinkQuiet(gbrainPath(LEGACY_SNOOZE_FILE));
}
// ── Refresh single-flight (anti-stampede) ────────────────────────────────────
/**
* Try to acquire the short-lived refresh lock so only ONE detached refresh runs
* when many invocations see a stale cache at once. Returns the lock path on
* success (caller must release it), or null if another process holds it.
* Separate from the upgrade mutex.
*/
export function tryAcquireRefreshLock(opts?: Pick<PackLockOpts, 'now' | 'isPidAlive'>, channel: ReleaseChannel = currentReleaseChannel() ?? DEFAULT_RELEASE_CHANNEL): string | null {
try {
const { lockPath } = acquirePackLock(`update-refresh-${channel}`, {
lockDir: locksDir(),
ttlMs: 30_000,
...opts,
});
return lockPath;
} catch {
return null;
}
}
export function releaseRefreshLock(lockPath: string): void {
try {
unlinkSync(lockPath);
} catch {
/* already gone */
}
}
// ── Swap receipt (what `gbrain upgrade --swap-only` actually installed) ──────
/**
* #6828: the autopilot channel names a file in this env var; `gbrain upgrade`
* writes what its swap installed there. Exit 0 alone cannot tell a swap from
* a no-op (`bun update` on a tag whose head is already installed exits 0 and
* changes nothing), and a no-op must never relaunch or record known-bad.
*/
export const SWAP_RECEIPT_ENV = 'GBRAIN_SWAP_RECEIPT';
/**
* - `installed`: a newer version is on disk and passed the post-swap smoke.
* - `not_installed`: the version did not change (the install step failed, or
* succeeded without installing anything newer).
* - `installed_broken`: a newer version is on disk and does not start.
*/
export interface SwapReceipt {
outcome: 'installed' | 'not_installed' | 'installed_broken';
from: string;
/** What `gbrain --version` reported after the swap; null when unreadable. */
installed: string | null;
}
/** Write the receipt when the caller asked for one. Best-effort. */
export function writeSwapReceipt(receipt: SwapReceipt): void {
const path = process.env[SWAP_RECEIPT_ENV];
if (!path) return;
try {
atomicWrite(path, JSON.stringify(receipt) + '\n');
} catch {
/* the channel falls back to the exit status */
}
}
/** Read a receipt; null when missing or malformed (the channel then trusts the exit status). */
export function readSwapReceipt(path: string): SwapReceipt | null {
try {
const r = JSON.parse(readFileSync(path, 'utf8')) as Partial<SwapReceipt>;
if (r.outcome !== 'installed' && r.outcome !== 'not_installed' && r.outcome !== 'installed_broken') return null;
if (typeof r.from !== 'string') return null;
const installed = typeof r.installed === 'string' && isValidVersionString(r.installed) ? r.installed : null;
return { outcome: r.outcome, from: r.from, installed };
} catch {
return null;
}
}
// ── Breadcrumb reconciliation (attribution for crash-on-launch) ──────────────
/** The mutable slice of `config.self_upgrade` the autopilot channel manages. */
export interface SelfUpgradeState {
mode?: SelfUpgradeMode;
/** Stored as written; `latest` (the pre-alpha name) reads as alpha. */
channel?: ReleaseChannel | 'latest';
mode_prompted?: boolean;
quiet_hours?: { start?: number; end?: number; tz?: string };
failed_versions?: string[];
attempting_version?: string;
last_check_ts?: number;
last_applied_version?: string;
/** #8776: `external` declares that a launcher outside gbrain's service starts autopilot again when it exits, so upgrades hand it over instead of refusing. */
autopilot_launcher?: 'external';
}
export type BreadcrumbTransition = 'applied' | 'failed' | null;
/**
* Reconcile the pre-swap breadcrumb at daemon boot (the post-swap "doctor gate"
* via attribution). Called by the relaunched binary:
*
* - No breadcrumb → nothing to do.
* - currentVersion >= breadcrumb → the swap+relaunch worked. The swap
* installs whatever is current at swap time (`git pull`, `bun update`,
* the release `latest-stable` names), so a release published after the update check lands
* a NEWER version than the breadcrumb names (#5813). Clear it, record
* `last_applied_version`, and drop `failed_versions` entries at or below
* the running version: `decideSelfUpgrade` only acts on a strictly newer
* release, so they can never be targeted again. (`applied`)
* - otherwise → we're NOT at the attempted version (the new binary crashed
* on launch and the supervisor relaunched the old one, or a stale
* breadcrumb, or an unparseable version). Record the attempted version in
* `failed_versions` so `decideSelfUpgrade` never retries it, and clear the
* breadcrumb. (`failed`)
*
* Pure: returns the next state + the transition; the caller persists + audits.
*/
export function reconcileBreadcrumb(
su: SelfUpgradeState | undefined,
currentVersion: string,
): { state: SelfUpgradeState; transition: BreadcrumbTransition } {
const state: SelfUpgradeState = { ...(su ?? {}) };
const attempting = state.attempting_version;
if (!attempting) return { state, transition: null };
const running = parseSemver(currentVersion);
const attempted = parseSemver(attempting);
if (attempting === currentVersion || (running && attempted && semverLte(attempted, running))) {
delete state.attempting_version;
state.last_applied_version = currentVersion;
if (state.failed_versions) {
// Unparseable entries stay: there is no ordering to prove them superseded.
const stillBad = state.failed_versions.filter((v) => {
const t = parseSemver(v);
return !t || !running || semverGt(t, running);
});
if (stillBad.length > 0) state.failed_versions = stillBad;
else delete state.failed_versions;
}
return { state, transition: 'applied' };
}
const failed = new Set(state.failed_versions ?? []);
failed.add(attempting);
state.failed_versions = [...failed];
delete state.attempting_version;
return { state, transition: 'failed' };
}
/** The audit reason the boot reconcile writes when it records a version known-bad (core/self-upgrade-recovery.ts matches on it, #6828). */
export const CRASH_ON_LAUNCH_REASON_PREFIX = 'crash-on-launch:';
/** The audit reason the channel writes when its swap installed a newer version and it exits for relaunch. */
export const SWAPPED_REASON = 'swapped; exiting for supervisor relaunch';
// ── Mode resolution (file plane; no DB on the hot path) ──────────────────────
function normalizeMode(raw: unknown): SelfUpgradeMode | null {
if (raw === 'auto' || raw === 'notify' || raw === 'off') return raw;
return null;
}
/**
* Resolve the effective mode from env > file-plane config > default `notify`.
* Takes a loosely-typed config so it doesn't pull the full GBrainConfig type
* onto the hot path. Env (`GBRAIN_SELF_UPGRADE_MODE`) is the operator / CI
* escape hatch.
*/
/** The `GBRAIN_SELF_UPGRADE_MODE` override, when it names a valid mode. */
export function selfUpgradeModeEnvOverride(): SelfUpgradeMode | null {
return normalizeMode(process.env.GBRAIN_SELF_UPGRADE_MODE);
}
export function resolveSelfUpgradeMode(
cfg: { self_upgrade?: { mode?: string } } | null | undefined,
): SelfUpgradeMode {
const env = selfUpgradeModeEnvOverride();
if (env) return env;
const fromCfg = normalizeMode(cfg?.self_upgrade?.mode);
if (fromCfg) return fromCfg;
return 'notify';
}
// ── `gbrain config set self_upgrade.<leaf>` (file plane) ─────────────────────
const QUIET_HOURS_DEFAULT_START = 23;
const QUIET_HOURS_DEFAULT_END = 8;
/** The autopilot silent channel's quiet-hours window: configured bounds, else
* 23:00-08:00 in the system timezone. `config set self_upgrade.quiet_hours`
* validates against the same resolution. */
export function resolveQuietHoursWindow(
qh: SelfUpgradeState['quiet_hours'],
): { start: number; end: number; tz: string } {
return {
start: qh?.start ?? QUIET_HOURS_DEFAULT_START,
end: qh?.end ?? QUIET_HOURS_DEFAULT_END,
tz: qh?.tz || Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC',
};
}
/** Every `self_upgrade.*` leaf `gbrain config set` accepts. All of them route
* to ~/.gbrain/config.json: each reader (the cli.ts startup check, the
* autopilot channel, doctor) reads the file plane only, so a DB-plane write
* would be accepted and never read (#5489). */
export const SELF_UPGRADE_CONFIG_LEAVES = [
'mode',
'channel',
'mode_prompted',
'quiet_hours',
'failed_versions',
'attempting_version',
'last_check_ts',
'last_applied_version',
'autopilot_launcher',
] as const satisfies readonly (keyof SelfUpgradeState)[];
export type SelfUpgradeConfigLeaf = (typeof SELF_UPGRADE_CONFIG_LEAVES)[number];
export type SelfUpgradeConfigParse =
| { ok: true; value: SelfUpgradeState[SelfUpgradeConfigLeaf] }
| { ok: false; error: string };
export function isSelfUpgradeConfigLeaf(leaf: string): leaf is SelfUpgradeConfigLeaf {
return (SELF_UPGRADE_CONFIG_LEAVES as readonly string[]).includes(leaf);
}
/** Normalize to the 4-segment form (`0.57.1` -> `0.57.1.0`): the upgrade
* machinery compares stored versions to the 4-segment latest by string, so a
* shorter spelling would be stored and never match. */
function parseVersionLeaf(raw: string): string | null {
const tuple = parseSemver(raw.trim());
return tuple ? tuple.join('.') : null;
}
function isHour(n: unknown): n is number {
return Number.isInteger(n) && (n as number) >= 0 && (n as number) <= 23;
}
function parseQuietHours(raw: string): SelfUpgradeConfigParse {
const shape = 'a JSON object like {"start":23,"end":8,"tz":"America/New_York"}';
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
return { ok: false, error: `must be ${shape}` };
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
return { ok: false, error: `must be ${shape}` };
}
const obj = parsed as Record<string, unknown>;
const unknownKeys = Object.keys(obj).filter((k) => k !== 'start' && k !== 'end' && k !== 'tz');
if (unknownKeys.length > 0) {
return { ok: false, error: `accepts only start, end and tz (got ${unknownKeys.join(', ')})` };
}
const out: { start?: number; end?: number; tz?: string } = {};
for (const k of ['start', 'end'] as const) {
if (obj[k] === undefined) continue;
if (!isHour(obj[k])) return { ok: false, error: `${k} must be an integer hour 0-23 (got ${JSON.stringify(obj[k])})` };
out[k] = obj[k];
}
if (obj.tz !== undefined) {
if (typeof obj.tz !== 'string' || !isValidTimeZone(obj.tz)) {
return { ok: false, error: `tz must be a valid IANA timezone (got ${JSON.stringify(obj.tz)})` };
}
out.tz = obj.tz;
}
// Validate what the autopilot reader will evaluate (defaults filled in) with
// the reader's own rule: a window evaluateQuietHours rejects is no window at
// all, so auto mode would never find a quiet hour to upgrade in.
if (!isValidQuietHoursWindow(resolveQuietHoursWindow(out))) {
return { ok: false, error: `start and end must differ (missing bounds default to ${QUIET_HOURS_DEFAULT_START} and ${QUIET_HOURS_DEFAULT_END})` };
}
return { ok: true, value: out };
}
function parseFailedVersions(raw: string): SelfUpgradeConfigParse {
const trimmed = raw.trim();
let items: unknown[];
if (trimmed.startsWith('[')) {
try {
const parsed = JSON.parse(trimmed);
if (!Array.isArray(parsed)) throw new Error('not an array');
items = parsed;
} catch {
return { ok: false, error: 'must be a JSON array of versions or a comma-separated list' };
}
} else {
items = trimmed === '' ? [] : trimmed.split(',');
}
const versions: string[] = [];
for (const item of items) {
const v = typeof item === 'string' ? parseVersionLeaf(item) : null;
if (!v) return { ok: false, error: `entries must be versions like 0.57.1.0 (got ${JSON.stringify(item)})` };
if (!versions.includes(v)) versions.push(v);
}
return { ok: true, value: versions };
}
/**
* Parse the raw `gbrain config set self_upgrade.<leaf> <value>` string into
* the typed value the file-plane readers expect. Refuses anything a reader
* would silently ignore (an unknown mode reads as `notify`).
*/
export function parseSelfUpgradeConfigValue(leaf: SelfUpgradeConfigLeaf, raw: string): SelfUpgradeConfigParse {
switch (leaf) {
case 'mode': {
const mode = normalizeMode(raw.trim());
return mode ? { ok: true, value: mode } : { ok: false, error: `must be auto, notify or off (got '${raw}')` };
}
case 'channel': {
const value = raw.trim();
return normalizeChannel(value) ? { ok: true, value } : { ok: false, error: `must be ${VALID_CHANNELS_TEXT} (got '${raw}')` };
}
case 'mode_prompted': {
if (isConfigTruthy(raw)) return { ok: true, value: true };
if (['false', '0', 'no', 'off'].includes(raw.trim().toLowerCase())) return { ok: true, value: false };
return { ok: false, error: `must be true or false (got '${raw}')` };
}
case 'autopilot_launcher':
return raw.trim() === 'external' ? { ok: true, value: 'external' } : { ok: false, error: `must be external (got '${raw}'); unset it to refuse upgrades while autopilot runs outside gbrain's service` };
case 'quiet_hours':
return parseQuietHours(raw);
case 'failed_versions':
return parseFailedVersions(raw);
case 'attempting_version':
case 'last_applied_version': {
const v = parseVersionLeaf(raw);
return v ? { ok: true, value: v } : { ok: false, error: `must be a version like 0.57.1.0 (got '${raw}')` };
}
case 'last_check_ts': {
const t = raw.trim();
const n = /^\d+$/.test(t) ? Number(t) : NaN;
return Number.isSafeInteger(n)
? { ok: true, value: n }
: { ok: false, error: `must be epoch milliseconds, an integer >= 0 (got '${raw}')` };
}
}
}