botmancers 0.1.0 → 0.4.2

package/dist/product.js

@@ -0,0 +1,1021 @@
+// The supervised Botmancers product: the packaged UI/API/core engine on
+// 127.0.0.1:43123 and the MCP bridge on 127.0.0.1:43124, run as two child
+// processes of one supervisor and reported as one health model.
+//
+//   start [--daemon] [--open]  launch (idempotent: an already healthy product is left alone)
+//   stop                       terminate the supervisor and both children
+//   status                     healthy / degraded / stopped, with versions and endpoints
+//   doctor                     preflight checks, including optional Hermes and Agent Deck
+//   open                       open the UI in a browser
+//
+// Health: healthy only when the supervisor and both children are alive, the
+// core's /api/health and the bridge's /healthz both answer with the installed
+// release version, and an authenticated bridge call reaches the core. Any
+// other running combination is degraded. Run metadata lives in
+// <home>/run/product.json and records each process's PID plus its start time;
+// metadata whose processes are gone is removed, and a PID is only signalled
+// when its start time and command line both still match the record. When the
+// identity cannot be verified nothing is signalled and the metadata is kept.
+import { spawn, execFileSync } from 'node:child_process';
+import { closeSync, existsSync, linkSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync, accessSync, constants as fsConstants } from 'node:fs';
+import { createServer } from 'node:net';
+import { delimiter, join } from 'node:path';
+import { DEFAULT_PORT, ENV } from './config.js';
+import { packageVersion } from './contract.js';
+import { CLI_PATH, HOME_DIRS, PRODUCT_HOST, UI_PORT_ENV, DEFAULT_UI_PORT, appDir, homePaths, missingAppFiles, modeOf, portFrom, readBuildInfo, readEnvFile, resolveHome, } from './home.js';
+import { RESTART_ACTION, START_LOCK_ENV, activateRelease, activatablePending, cliEntryIn, beginHandOff, handOffFileLock, managedPaths, managedReport, scheduleAutoUpdate, versionDir, waitForFileLock, writeUpdateState } from './managed.js';
+import { createRedactor } from './redact.js';
+import { BRIDGE_SERVICE_ID, SERVICE_TOKENS_ENV, credentialState } from './setup.js';
+import { clientDoctorLines, mcpTarget } from './clients.js';
+export const PRODUCT_EXIT = {
+    ok: 0,
+    degraded: 1, // running but not healthy; doctor found a problem; browser launch failed
+    usage: 2,
+    stopped: 3, // status/open: not running
+    portInUse: 6,
+    childFailed: 7, // the core or the bridge did not come up
+    missingAssets: 8, // the packaged app is incomplete
+    home: 9, // BOTMANCERS_HOME is not writable
+    notSetUp: 10, // run `botmancers setup` first
+    clientMissing: 11, // setup --client: that client is not installed for this user
+    clientConflict: 12, // setup --client: its files are not Botmancers-managed; nothing written
+};
+export const STARTUP_TIMEOUT_ENV = 'BOTMANCERS_STARTUP_TIMEOUT_MS';
+export const BROWSER_ENV = 'BOTMANCERS_BROWSER';
+export const AGENT_DECK_URL_ENV = 'BOTMANCERS_AGENT_DECK_URL';
+export const CORE_HEALTH_PATH = '/api/health';
+export const BRIDGE_HEALTH_PATH = '/healthz';
+const DEFAULT_STARTUP_TIMEOUT_MS = 60_000;
+const DEFAULT_AGENT_DECK_URL = 'http://127.0.0.1:1111';
+export class UsageError extends Error {
+}
+export function productContext(env, io) {
+    const paths = homePaths(resolveHome(env));
+    let uiPort;
+    let mcpPort;
+    try {
+        uiPort = portFrom(env, UI_PORT_ENV, DEFAULT_UI_PORT);
+        mcpPort = portFrom(env, ENV.port, DEFAULT_PORT);
+    }
+    catch (error) {
+        throw new UsageError(error.message);
+    }
+    const bridge = readEnvFile(paths.bridgeEnv) ?? {};
+    const redact = createRedactor([bridge[ENV.serviceToken], bridge[ENV.mcpToken], env[ENV.serviceToken], env[ENV.mcpToken]]);
+    const out = (write) => (text) => write(redact(text));
+    return { env, io: { stdout: out(io.stdout), stderr: out(io.stderr) }, paths, appDir: appDir(env), uiPort, mcpPort, version: packageVersion(), redact };
+}
+const uiUrl = (ctx) => `http://${PRODUCT_HOST}:${ctx.uiPort}`;
+const mcpBase = (ctx) => `http://${PRODUCT_HOST}:${ctx.mcpPort}`;
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+function startupTimeout(env) {
+    const value = Number(env[STARTUP_TIMEOUT_ENV]);
+    return Number.isFinite(value) && value > 0 ? value : DEFAULT_STARTUP_TIMEOUT_MS;
+}
+// How long a start (or an explicit activation) waits for another start to
+// claim the home: as long as a daemon start waits for its supervisor.
+export function startLockTimeout(env) {
+    return startupTimeout(env) * 2 + 5000;
+}
+export function readRun(paths) {
+    try {
+        const record = JSON.parse(readFileSync(paths.runFile, 'utf8'));
+        return record && record.schema === 1 && typeof record.supervisor?.pid === 'number' ? record : null;
+    }
+    catch {
+        return null;
+    }
+}
+// The run record is replaced atomically (owner-only temp file, then rename),
+// so a concurrent status, doctor, open, or start never reads a truncated
+// file and mistakes it for stale metadata. Start creates it exclusively the
+// same way: link() publishes the finished file and fails with EEXIST when
+// another start already owns the home.
+export function writeRun(paths, record, exclusive = false) {
+    const temp = `${paths.runFile}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    try {
+        if (exclusive)
+            linkSync(temp, paths.runFile);
+        else
+            renameSync(temp, paths.runFile);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+export function pidAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+// The start time and command line of a live process, null when it is gone,
+// or 'unverifiable' when this platform cannot tell (no ps, a failing ps,
+// unparseable output). Fails closed: a ps failure only means "gone" when an
+// independent liveness check also says the pid is not running.
+export function processIdentity(pid) {
+    let out;
+    try {
+        out = execFileSync('ps', ['-p', String(pid), '-o', 'lstart=', '-o', 'command='], {
+            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, LC_ALL: 'C' },
+        });
+    }
+    catch {
+        return pidAlive(pid) ? 'unverifiable' : null;
+    }
+    const match = /^\s*(\w{3} \w{3} +\d+ \d\d:\d\d:\d\d \d{4})\s+(.*)$/.exec(out.trim());
+    return match ? { started: match[1].replace(/ +/g, ' '), command: match[2] } : 'unverifiable';
+}
+export function processStarted(pid) {
+    if (!pid)
+        return undefined;
+    const identity = processIdentity(pid);
+    return identity && identity !== 'unverifiable' ? identity.started : undefined;
+}
+export function ownership(pid, started, markers) {
+    if (!pidAlive(pid))
+        return 'gone';
+    const identity = processIdentity(pid);
+    if (identity === 'unverifiable')
+        return 'unverified';
+    if (identity === null)
+        return 'gone';
+    if (!markers.some(marker => identity.command.includes(marker)))
+        return 'gone';
+    if (!started)
+        return 'unverified';
+    return identity.started === started ? 'owned' : 'gone';
+}
+// A foreground `botmancers start` may run through the npm bin link. The
+// recorded CLI path matters after a managed release switch: a product started
+// from versions/N must still be recognized by the CLI of versions/N+1.
+const supervisorMarkers = (record) => [record.cli ?? CLI_PATH, 'botmancers'];
+const bridgeMarkers = (record) => [`${record.cli ?? CLI_PATH} mcp`];
+// Next renames its process to "next-server (vX)" on some platforms; the
+// recorded start time is what tells ours apart from any other Next server.
+const coreMarkers = (record) => [join(record.appDir, 'server.js'), 'next-server'];
+function targetsOf(record) {
+    return [
+        { name: 'supervisor', pid: record.supervisor.pid, owner: ownership(record.supervisor.pid, record.supervisor.started, supervisorMarkers(record)) },
+        { name: 'core', pid: record.ui.pid, owner: ownership(record.ui.pid, record.ui.started, coreMarkers(record)) },
+        { name: 'bridge', pid: record.mcp.pid, owner: ownership(record.mcp.pid, record.mcp.started, bridgeMarkers(record)) },
+    ];
+}
+const unverifiedNote = (targets) => `cannot verify that ${targets.map(t => `${t.name} pid ${t.pid}`).join(', ')} ${targets.length > 1 ? 'are' : 'is'} botmancers (no start-time identity); not signalled`;
+async function getJson(url, init = {}, timeoutMs = 2500) {
+    const response = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs), redirect: 'error' });
+    const text = await response.text();
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        body = null;
+    }
+    return { status: response.status, body };
+}
+function unreachable(error) {
+    const cause = error.cause?.code ?? error.name;
+    return `not answering (${cause})`;
+}
+export async function probeCore(url) {
+    try {
+        const { status, body } = await getJson(`${url}${CORE_HEALTH_PATH}`);
+        if (status !== 200 || body?.service !== 'botmancers-core' || body?.status !== 'ok') {
+            return { ok: false, version: typeof body?.version === 'string' ? body.version : null, detail: `unhealthy (HTTP ${status})`, body: body ?? undefined };
+        }
+        return { ok: true, version: String(body.version), detail: 'ok', body };
+    }
+    catch (error) {
+        return { ok: false, version: null, detail: unreachable(error) };
+    }
+}
+export async function probeBridge(base) {
+    try {
+        const { status, body } = await getJson(`${base}${BRIDGE_HEALTH_PATH}`);
+        if (status !== 200 || body?.status !== 'ok')
+            return { ok: false, version: null, detail: `unhealthy (HTTP ${status})` };
+        return { ok: true, version: String(body.version), detail: 'ok', body };
+    }
+    catch (error) {
+        return { ok: false, version: null, detail: unreachable(error) };
+    }
+}
+// An authenticated, read-only bridge round trip that the bridge forwards to
+// the core: proves the bridge reaches this engine with valid credentials.
+export async function probeLink(base, mcpToken) {
+    if (!mcpToken)
+        return { ok: false, version: null, detail: 'no MCP token in bridge.env' };
+    try {
+        const { status, body } = await getJson(`${base}/mcp`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', accept: 'application/json', authorization: `Bearer ${mcpToken}` },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 'botmancers-status', method: 'tools/call', params: { name: 'botmancers_health', arguments: {} } }),
+        }, 5000);
+        const result = (body?.result ?? null);
+        if (status !== 200 || !result || result.isError || result.structuredContent?.status !== 'ok') {
+            const message = body?.error?.message;
+            return { ok: false, version: null, detail: `bridge call failed (HTTP ${status}${message ? `: ${message.slice(0, 160)}` : ''})` };
+        }
+        const principal = result.structuredContent.principal;
+        return { ok: true, version: null, detail: `ok (${principal?.kind}:${principal?.id})` };
+    }
+    catch (error) {
+        return { ok: false, version: null, detail: unreachable(error) };
+    }
+}
+export function portFree(port, host = PRODUCT_HOST) {
+    return new Promise(resolve => {
+        const server = createServer();
+        server.once('error', () => resolve(false));
+        server.listen(port, host, () => server.close(() => resolve(true)));
+    });
+}
+export async function inspect(ctx) {
+    const record = readRun(ctx.paths);
+    const none = { supervisor: false, ui: false, mcp: false };
+    if (!record) {
+        const stray = existsSync(ctx.paths.runFile);
+        if (stray)
+            rmSync(ctx.paths.runFile, { force: true });
+        return { state: 'stopped', record: null, problems: [], repaired: stray ? 'removed unreadable run metadata' : null, alive: none, core: null, bridge: null, link: null };
+    }
+    const targets = targetsOf(record);
+    const [supervisor, ui, mcp] = targets.map(target => target.owner === 'owned');
+    const alive = { supervisor, ui, mcp };
+    const unverified = targets.filter(target => target.owner === 'unverified');
+    if (targets.every(target => target.owner === 'gone')) {
+        rmSync(ctx.paths.runFile, { force: true });
+        return {
+            state: 'stopped', record: null, problems: [], alive, core: null, bridge: null, link: null,
+            repaired: `removed stale run metadata (supervisor pid ${record.supervisor.pid} is not running)`,
+        };
+    }
+    const [core, bridge] = await Promise.all([probeCore(record.ui.url), probeBridge(record.mcp.url.replace(/\/mcp$/, ''))]);
+    // The link probe is the only credential-bearing request: it carries the
+    // owner-only MCP bearer token to the bridge, which forwards the service
+    // token to the core. Both listeners must therefore be confirmed ours; a
+    // process that is gone or unverifiable may be another program on its port.
+    const link = bridge.ok && core.ok && mcp && ui ? await probeLink(record.mcp.url.replace(/\/mcp$/, ''), readEnvFile(ctx.paths.bridgeEnv)?.[ENV.mcpToken]) : null;
+    const problems = [];
+    if (unverified.length)
+        problems.push(unverifiedNote(unverified));
+    if (record.state === 'starting')
+        problems.push('startup has not finished');
+    if (record.state === 'stopping')
+        problems.push('shutdown in progress');
+    const isUnverified = (name) => unverified.some(target => target.name === name);
+    if (!alive.supervisor && !isUnverified('supervisor'))
+        problems.push(`supervisor (pid ${record.supervisor.pid}) is not running`);
+    if (!alive.ui && !isUnverified('core'))
+        problems.push(`core (pid ${record.ui.pid ?? '-'}) is not running${record.ui.exited ? ` (exited ${record.ui.exited.code ?? record.ui.exited.signal})` : ''}`);
+    if (!alive.mcp && !isUnverified('bridge'))
+        problems.push(`bridge (pid ${record.mcp.pid ?? '-'}) is not running${record.mcp.exited ? ` (exited ${record.mcp.exited.code ?? record.mcp.exited.signal})` : ''}`);
+    if (!core.ok)
+        problems.push(`core health ${core.detail}`);
+    else if (core.version !== ctx.version)
+        problems.push(`version mismatch: core reports ${core.version}, installed ${ctx.version}`);
+    else if (core.body?.home !== ctx.paths.home)
+        problems.push(`core is serving another home (${String(core.body?.home)})`);
+    if (!bridge.ok)
+        problems.push(`bridge health ${bridge.detail}`);
+    else if (bridge.version !== ctx.version)
+        problems.push(`version mismatch: bridge reports ${bridge.version}, installed ${ctx.version}`);
+    if (link && !link.ok)
+        problems.push(`bridge -> core ${link.detail}`);
+    if (record.version !== ctx.version)
+        problems.push(`started by botmancers ${record.version}, installed ${ctx.version}`);
+    return { state: problems.length ? 'degraded' : 'healthy', record, problems, repaired: null, alive, core, bridge, link };
+}
+// Install kind, launcher, and the versions that are installed, staged, and
+// actually running. The running versions come only from the live health
+// endpoints: a staged release or a moved `current` link never counts.
+function installLines(ctx, view, report) {
+    const lines = [`  install     ${report.install.kind} (${report.install.cliPath})`];
+    if (report.launcher) {
+        lines.push(`  launcher    ${report.paths.launcher}${report.shadowedBy ? ` (shadowed on PATH by ${report.shadowedBy})` : report.resolved ? '' : ' (not on PATH)'}`);
+    }
+    else if (report.resolved) {
+        lines.push(`  launcher    PATH resolves botmancers to ${report.resolved}`);
+    }
+    const versions = [`cli ${ctx.version}`];
+    if (report.current)
+        versions.push(`current ${report.current}`);
+    if (report.pending)
+        versions.push(`pending ${report.pending} (staged, not running${report.autoupdate ? '' : '; auto-update disabled'})`);
+    lines.push(`  versions    ${versions.join(', ')}`);
+    if (view.record) {
+        const shown = (probe) => probe?.version ?? (probe?.ok === false ? 'down' : 'unknown');
+        lines.push(`  running     core ${shown(view.core)}, bridge ${shown(view.bridge)} (started by ${view.record.version})`);
+    }
+    return lines;
+}
+export function formatStatus(ctx, view, report = managedReport(ctx.env)) {
+    const lines = [`botmancers ${ctx.version}: ${view.state}`];
+    if (view.repaired)
+        lines.push(`  note        ${view.repaired}`);
+    lines.push(`  home        ${ctx.paths.home}`);
+    lines.push(...installLines(ctx, view, report));
+    const activates = report.pending && report.autoupdate ? `   (activates ${report.pending})` : '';
+    const record = view.record;
+    if (record) {
+        const show = (probe) => (probe ? `${probe.ok ? 'ok' : 'DOWN'}${probe.version ? ` version ${probe.version}` : ''}` : '-');
+        lines.push(`  ui/core     ${record.ui.url}  ${show(view.core)} (pid ${record.ui.pid ?? '-'})`);
+        lines.push(`  mcp bridge  ${record.mcp.url}  ${show(view.bridge)} (pid ${record.mcp.pid ?? '-'})`);
+        if (view.link)
+            lines.push(`  bridge→core ${view.link.detail}`);
+        lines.push(`  supervisor  pid ${record.supervisor.pid}${view.alive.supervisor ? '' : ' (not running)'}, started ${record.startedAt}`);
+        for (const problem of view.problems)
+            lines.push(`  problem     ${problem}`);
+        if (view.state === 'degraded')
+            lines.push(`  fix         ${RESTART_ACTION}   (logs: ${ctx.paths.logs})${activates}`);
+        else if (activates)
+            lines.push(`  restart     ${RESTART_ACTION}${activates}`);
+    }
+    else {
+        lines.push(`  ui/core     ${uiUrl(ctx)}  (not running)`);
+        lines.push(`  mcp bridge  ${mcpBase(ctx)}/mcp  (not running)`);
+        if (activates)
+            lines.push(`  next start  botmancers start --daemon${activates}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+export async function status(ctx) {
+    const view = await inspect(ctx);
+    ctx.io.stdout(formatStatus(ctx, view));
+    return view.state === 'healthy' ? PRODUCT_EXIT.ok : view.state === 'degraded' ? PRODUCT_EXIT.degraded : PRODUCT_EXIT.stopped;
+}
+// ---------------------------------------------------------------------
+// Preconditions shared by start and doctor.
+function homeWritable(paths) {
+    try {
+        accessSync(paths.home, fsConstants.W_OK);
+        for (const dir of HOME_DIRS)
+            accessSync(join(paths.home, dir), fsConstants.W_OK);
+        const probe = join(paths.run, `.write-probe-${process.pid}`);
+        writeFileSync(probe, '');
+        rmSync(probe);
+        return null;
+    }
+    catch (error) {
+        return error.code ?? 'unwritable';
+    }
+}
+function preconditions(ctx) {
+    const missing = missingAppFiles(ctx.appDir);
+    if (missing.length) {
+        return { code: PRODUCT_EXIT.missingAssets, message: `the packaged app at ${ctx.appDir} is incomplete (missing ${missing.join(', ')}). Reinstall botmancers.` };
+    }
+    if (!existsSync(ctx.paths.home)) {
+        return { code: PRODUCT_EXIT.notSetUp, message: `${ctx.paths.home} does not exist. Run: botmancers setup` };
+    }
+    const unwritable = homeWritable(ctx.paths);
+    if (unwritable === 'ENOENT')
+        return { code: PRODUCT_EXIT.notSetUp, message: `${ctx.paths.home} is not fully set up. Run: botmancers setup` };
+    if (unwritable)
+        return { code: PRODUCT_EXIT.home, message: `BOTMANCERS_HOME ${ctx.paths.home} is not writable (${unwritable}). Fix its permissions or choose another BOTMANCERS_HOME.` };
+    const credentials = credentialState(ctx.paths);
+    if (!credentials.ok)
+        return { code: PRODUCT_EXIT.notSetUp, message: `${credentials.problems.join('; ')}. Run: botmancers setup` };
+    return null;
+}
+// ---------------------------------------------------------------------
+// The supervisor.
+// BOTMANCERS_SERVICE_TOKENS is a list of `<service-id>=sha256:<hex>` entries.
+// An operator's explicit entries stay authoritative; the generated internal
+// bridge entry is merged in and always wins its own id, so the bridge can
+// authenticate whatever the shell exports. Later entries replace earlier ones
+// with the same id (config file, then shell, then the generated entry).
+export function mergeServiceTokens(generated, ...explicit) {
+    const entries = new Map();
+    const add = (list) => {
+        for (const entry of (list ?? '').split(/[,\s]+/).filter(Boolean)) {
+            const id = entry.slice(0, Math.max(entry.indexOf('='), 0));
+            entries.set(id || entry, entry);
+        }
+    };
+    for (const list of explicit)
+        add(list);
+    const bridge = (generated ?? '').split(/[,\s]+/).filter(entry => entry.startsWith(`${BRIDGE_SERVICE_ID}=`));
+    entries.delete(BRIDGE_SERVICE_ID);
+    for (const entry of bridge)
+        entries.set(BRIDGE_SERVICE_ID, entry);
+    return [...entries.values()].join(',');
+}
+function childEnvs(ctx) {
+    const coreFile = readEnvFile(ctx.paths.coreEnv) ?? {};
+    const bridgeFile = readEnvFile(ctx.paths.bridgeEnv) ?? {};
+    const shell = { ...ctx.env };
+    // The core never holds the raw bridge tokens.
+    for (const key of [ENV.serviceToken, ENV.mcpToken, ENV.url, ENV.host, ENV.port, UI_PORT_ENV])
+        delete shell[key];
+    const home = ctx.paths.home;
+    return {
+        core: {
+            ...coreFile,
+            ...shell,
+            [SERVICE_TOKENS_ENV]: mergeServiceTokens(coreFile[SERVICE_TOKENS_ENV], coreFile[SERVICE_TOKENS_ENV], shell[SERVICE_TOKENS_ENV]),
+            BOTMANCERS_HOME: home,
+            PORT: String(ctx.uiPort),
+            HOSTNAME: PRODUCT_HOST,
+            NODE_ENV: 'production',
+            NEXT_TELEMETRY_DISABLED: '1',
+        },
+        bridge: {
+            ...shell,
+            [ENV.serviceToken]: bridgeFile[ENV.serviceToken],
+            [ENV.mcpToken]: bridgeFile[ENV.mcpToken],
+            [ENV.url]: uiUrl(ctx),
+            [ENV.host]: PRODUCT_HOST,
+            [ENV.port]: String(ctx.mcpPort),
+            BOTMANCERS_HOME: home,
+        },
+    };
+}
+function spawnLogged(args, options) {
+    const fd = openSync(options.log, 'a', 0o600);
+    try {
+        return spawn(process.execPath, args, { cwd: options.cwd, env: options.env, stdio: ['ignore', fd, fd] });
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+async function waitUntil(child, check, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return 'exited';
+        if (await check())
+            return 'ready';
+        await sleep(200);
+    }
+    return 'timeout';
+}
+function terminate(children, graceMs = 8000) {
+    const live = children.filter(child => child.exitCode === null && child.signalCode === null);
+    if (!live.length)
+        return Promise.resolve();
+    return new Promise(resolve => {
+        let pending = live.length;
+        const timer = setTimeout(() => {
+            for (const child of live)
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill('SIGKILL');
+        }, graceMs);
+        for (const child of live) {
+            child.once('exit', () => {
+                if (--pending === 0) {
+                    clearTimeout(timer);
+                    resolve();
+                }
+            });
+            child.kill('SIGTERM');
+        }
+    });
+}
+function tail(path, from, maxLines = 12) {
+    try {
+        const size = statSync(path).size;
+        if (size <= from)
+            return [];
+        const fd = openSync(path, 'r');
+        const buffer = Buffer.alloc(Math.min(size - from, 64 * 1024));
+        readSync(fd, buffer, 0, buffer.length, size - buffer.length);
+        closeSync(fd);
+        return buffer.toString('utf8').trimEnd().split('\n').slice(-maxLines);
+    }
+    catch {
+        return [];
+    }
+}
+const logSize = (path) => { try {
+    return statSync(path).size;
+}
+catch {
+    return 0;
+} };
+// Runs the product in this process until a signal. Resolves with an exit
+// code when startup fails or after a signal-initiated shutdown; calls
+// onReady once both children are healthy.
+export async function supervise(ctx, onReady, onClaim = () => { }) {
+    const log = (line) => ctx.io.stderr(`[${new Date().toISOString()}] botmancers supervisor: ${line}\n`);
+    const record = {
+        schema: 1,
+        version: ctx.version,
+        home: ctx.paths.home,
+        appDir: ctx.appDir,
+        state: 'starting',
+        startedAt: new Date().toISOString(),
+        supervisor: { pid: process.pid, started: processStarted(process.pid) },
+        cli: CLI_PATH,
+        ui: { pid: null, port: ctx.uiPort, url: uiUrl(ctx) },
+        mcp: { pid: null, port: ctx.mcpPort, url: `${mcpBase(ctx)}/mcp` },
+    };
+    try {
+        writeRun(ctx.paths, record, true);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        log('another botmancers start owns this home; leaving it alone.');
+        return PRODUCT_EXIT.degraded;
+    }
+    finally {
+        onClaim();
+    }
+    const owned = () => readRun(ctx.paths)?.supervisor.pid === process.pid;
+    const save = () => { if (owned())
+        writeRun(ctx.paths, record); };
+    const children = [];
+    let shuttingDown = false;
+    const fail = async (code, message) => {
+        shuttingDown = true;
+        log(message);
+        await terminate(children);
+        if (owned())
+            rmSync(ctx.paths.runFile, { force: true });
+        return code;
+    };
+    const envs = childEnvs(ctx);
+    const timeout = startupTimeout(ctx.env);
+    const watch = (name, child) => {
+        child.on('exit', (code, signal) => {
+            record[name].exited = { code, signal, at: new Date().toISOString() };
+            if (shuttingDown)
+                return;
+            log(`${name === 'ui' ? 'core' : 'bridge'} (pid ${child.pid}) exited unexpectedly (${code ?? signal}); the product is degraded. See ${name === 'ui' ? ctx.paths.uiLog : ctx.paths.mcpLog}.`);
+            save();
+        });
+    };
+    log(`starting botmancers ${ctx.version} (home ${ctx.paths.home})`);
+    const coreLogStart = logSize(ctx.paths.uiLog);
+    const ui = spawnLogged([join(ctx.appDir, 'server.js')], { cwd: ctx.appDir, env: envs.core, log: ctx.paths.uiLog });
+    children.push(ui);
+    record.ui.pid = ui.pid ?? null;
+    record.ui.started = processStarted(ui.pid);
+    watch('ui', ui);
+    save();
+    const coreUp = await waitUntil(ui, async () => (await probeCore(record.ui.url)).ok, timeout);
+    if (coreUp !== 'ready') {
+        const why = tail(ctx.paths.uiLog, coreLogStart).map(line => `    ${line}`).join('\n');
+        const inUse = /EADDRINUSE/.test(why);
+        return fail(inUse ? PRODUCT_EXIT.portInUse : PRODUCT_EXIT.childFailed, `degraded start: the core ${coreUp === 'exited' ? `exited (${ui.exitCode ?? ui.signalCode})` : `did not become healthy within ${timeout} ms`}${inUse ? `: port ${ctx.uiPort} is in use` : ''}; nothing left running. Log ${ctx.paths.uiLog}:\n${why}`);
+    }
+    log(`core healthy at ${record.ui.url} (pid ${ui.pid})`);
+    const bridgeLogStart = logSize(ctx.paths.mcpLog);
+    const mcp = spawnLogged([CLI_PATH, 'mcp'], { cwd: ctx.paths.home, env: envs.bridge, log: ctx.paths.mcpLog });
+    children.push(mcp);
+    record.mcp.pid = mcp.pid ?? null;
+    record.mcp.started = processStarted(mcp.pid);
+    watch('mcp', mcp);
+    save();
+    const bridgeUp = await waitUntil(mcp, async () => (await probeBridge(mcpBase(ctx))).ok, timeout);
+    if (bridgeUp !== 'ready') {
+        const why = tail(ctx.paths.mcpLog, bridgeLogStart).map(line => `    ${ctx.redact(line)}`).join('\n');
+        const inUse = mcp.exitCode === 3;
+        return fail(inUse ? PRODUCT_EXIT.portInUse : PRODUCT_EXIT.childFailed, `degraded start: the core started but the bridge ${bridgeUp === 'exited' ? `exited (${mcp.exitCode ?? mcp.signalCode})` : `did not become healthy within ${timeout} ms`}${inUse ? `: port ${ctx.mcpPort} is in use` : ''}; stopped the core too. Log ${ctx.paths.mcpLog}:\n${why}`);
+    }
+    log(`bridge healthy at ${record.mcp.url} (pid ${mcp.pid})`);
+    record.state = 'running';
+    save();
+    onReady(record);
+    // The running product checks for updates (at most daily, in a detached
+    // worker); a staged release waits for the next start.
+    scheduleAutoUpdate(ctx.env);
+    setInterval(() => scheduleAutoUpdate(ctx.env), 60 * 60 * 1000).unref();
+    return new Promise(resolve => {
+        const stop = (signal) => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            log(`${signal} received; stopping core and bridge.`);
+            record.state = 'stopping';
+            save();
+            terminate(children).then(() => {
+                if (owned())
+                    rmSync(ctx.paths.runFile, { force: true });
+                log('stopped.');
+                resolve(PRODUCT_EXIT.ok);
+            });
+        };
+        process.once('SIGTERM', () => stop('SIGTERM'));
+        process.once('SIGINT', () => stop('SIGINT'));
+        process.once('SIGHUP', () => stop('SIGHUP'));
+    });
+}
+// ---------------------------------------------------------------------
+// Commands.
+function browserCommand(env) {
+    const custom = (env[BROWSER_ENV] ?? '').trim();
+    if (custom)
+        return custom.split(/\s+/);
+    if (process.platform === 'darwin')
+        return ['open'];
+    if (process.platform === 'win32')
+        return ['cmd', '/c', 'start', '""'];
+    return ['xdg-open'];
+}
+function launchBrowser(ctx, url) {
+    const [command, ...args] = browserCommand(ctx.env);
+    return new Promise(resolve => {
+        const child = spawn(command, [...args, url], { stdio: 'ignore', detached: true });
+        child.once('error', () => resolve(false));
+        child.once('spawn', () => {
+            child.unref();
+            resolve(true);
+        });
+    });
+}
+export async function open(ctx) {
+    const view = await inspect(ctx);
+    if (view.state === 'stopped' || !view.core?.ok) {
+        ctx.io.stderr(`botmancers: the UI is not running (${view.state}). Start it with: botmancers start --daemon --open\n`);
+        return PRODUCT_EXIT.stopped;
+    }
+    const url = view.record.ui.url;
+    if (await launchBrowser(ctx, url)) {
+        ctx.io.stdout(`botmancers: opened ${url}\n`);
+        return PRODUCT_EXIT.ok;
+    }
+    ctx.io.stderr(`botmancers: could not launch a browser; open ${url} yourself.\n`);
+    return PRODUCT_EXIT.degraded;
+}
+export function parseStartArgs(argv) {
+    const options = { daemon: false, open: false, supervise: false };
+    for (const arg of argv) {
+        if (arg === '--daemon' || arg === '-d')
+            options.daemon = true;
+        else if (arg === '--open')
+            options.open = true;
+        else if (arg === '--supervise')
+            options.supervise = true; // internal: the detached supervisor
+        else
+            throw new UsageError(/^--?[a-z][a-z0-9-]{0,38}$/.test(arg) ? `Unknown argument ${JSON.stringify(arg)} for start.` : 'Unexpected argument for start (value not shown).');
+    }
+    return options;
+}
+export async function start(ctx, options) {
+    const blocked = preconditions(ctx);
+    if (blocked) {
+        ctx.io.stderr(`botmancers: ${blocked.message}\n`);
+        return blocked.code;
+    }
+    if (options.supervise) {
+        // The detached supervisor started by `start --daemon`; its parent already checked.
+        const code = await supervise(ctx, () => { });
+        return code;
+    }
+    // The stopped proof, a pending release's activation, and the supervisor's
+    // claim on the home (its run record) happen under start.lock, so neither a
+    // concurrent start nor an explicit upgrade can act between them.
+    const lock = await waitForFileLock(managedPaths(ctx.env).startLock, {
+        timeoutMs: startLockTimeout(ctx.env),
+        inherit: ctx.env[START_LOCK_ENV],
+        onWait: () => ctx.io.stderr('botmancers: waiting for another botmancers start or upgrade of this home...\n'),
+    });
+    if (!lock) {
+        ctx.io.stderr(`botmancers: another botmancers start or upgrade of ${ctx.paths.home} did not finish; run \`botmancers status\`.\n`);
+        return PRODUCT_EXIT.degraded;
+    }
+    try {
+        return await startLocked(ctx, options, lock);
+    }
+    finally {
+        lock.release();
+    }
+}
+async function startLocked(ctx, options, lock) {
+    const view = await inspect(ctx);
+    if (view.repaired)
+        ctx.io.stderr(`botmancers: ${view.repaired}\n`);
+    if (view.state === 'healthy') {
+        ctx.io.stdout(`botmancers: already running.\n${formatStatus(ctx, view)}`);
+        if (options.open)
+            await launchBrowser(ctx, view.record.ui.url);
+        return PRODUCT_EXIT.ok;
+    }
+    if (view.state === 'degraded') {
+        ctx.io.stdout(formatStatus(ctx, view));
+        ctx.io.stderr('botmancers: a previous start is degraded; see the fix line above.\n');
+        return PRODUCT_EXIT.degraded;
+    }
+    // Nothing from this home is live (inspect proved every recorded process is
+    // gone) and no other start can begin until this one's supervisor claims the
+    // home, so a staged managed release can become current now (NOT-279).
+    const activated = await activatePendingAndRestart(ctx, options, lock);
+    if (activated !== null)
+        return activated;
+    for (const [port, what] of [[ctx.uiPort, 'UI/core'], [ctx.mcpPort, 'MCP bridge']]) {
+        if (!(await portFree(port))) {
+            ctx.io.stderr(`botmancers: port ${port} on ${PRODUCT_HOST} (${what}) is in use by another process. Stop it, or choose another port with ${what === 'UI/core' ? UI_PORT_ENV : ENV.port}.\n`);
+            return PRODUCT_EXIT.portInUse;
+        }
+    }
+    const announce = async (record) => {
+        ctx.io.stdout(`botmancers ${ctx.version}: running\n  UI   ${record.ui.url}\n  MCP  ${record.mcp.url}\n  home ${ctx.paths.home}\n`);
+        if (options.open) {
+            if (!(await launchBrowser(ctx, record.ui.url)))
+                ctx.io.stderr(`botmancers: could not launch a browser; open ${record.ui.url} yourself.\n`);
+        }
+    };
+    if (!options.daemon) {
+        const code = await supervise({ ...ctx, io: { stdout: ctx.io.stdout, stderr: ctx.io.stderr } }, record => { void announce(record); }, lock.release);
+        return code;
+    }
+    const { [START_LOCK_ENV]: _inherited, ...childEnv } = ctx.env;
+    const from = logSize(ctx.paths.supervisorLog);
+    const fd = openSync(ctx.paths.supervisorLog, 'a', 0o600);
+    const child = spawn(process.execPath, [CLI_PATH, 'start', '--supervise'], {
+        cwd: ctx.paths.home,
+        env: { ...childEnv, BOTMANCERS_HOME: ctx.paths.home },
+        detached: true,
+        stdio: ['ignore', fd, fd],
+    });
+    closeSync(fd);
+    let exitCode = null;
+    child.once('exit', code => { exitCode = code ?? PRODUCT_EXIT.childFailed; });
+    const deadline = Date.now() + startupTimeout(ctx.env) * 2 + 5000;
+    while (Date.now() < deadline) {
+        await sleep(250);
+        if (exitCode !== null)
+            break;
+        const record = readRun(ctx.paths);
+        // The supervisor has claimed the home: later starts see it as live.
+        if (record?.supervisor.pid === child.pid)
+            lock.release();
+        if (record?.state === 'running' && record.supervisor.pid === child.pid) {
+            child.unref();
+            await announce(record);
+            return PRODUCT_EXIT.ok;
+        }
+    }
+    if (exitCode === null) {
+        child.kill('SIGTERM');
+        exitCode = PRODUCT_EXIT.childFailed;
+    }
+    ctx.io.stderr(`botmancers: start failed (exit ${exitCode}). Supervisor log ${ctx.paths.supervisorLog}:\n`);
+    for (const line of tail(ctx.paths.supervisorLog, from, 40))
+        ctx.io.stderr(`  ${line}\n`);
+    return exitCode;
+}
+// Switches `current` to the staged release and hands this start over to the
+// new release's CLI, which owns start.lock (handed off by token) until its
+// supervisor claims the home. Returns null when there is nothing to activate.
+async function activatePendingAndRestart(ctx, options, lock) {
+    const pending = activatablePending(ctx.env);
+    if (!pending)
+        return null;
+    const paths = managedPaths(ctx.env);
+    try {
+        activateRelease(paths, pending);
+    }
+    catch (error) {
+        writeUpdateState(paths, { pendingVersion: null, pendingIntegrity: null, stagedAt: null, lastError: error.message });
+        ctx.io.stderr(`botmancers: not activating ${pending}: ${error.message}; starting ${ctx.version}.\n`);
+        return null;
+    }
+    ctx.io.stdout(`botmancers: activated ${pending} (was ${ctx.version}).\n`);
+    const args = [cliEntryIn(versionDir(paths, pending)), 'start', ...(options.daemon ? ['--daemon'] : []), ...(options.open ? ['--open'] : [])];
+    // Announce the hand-off before spawning: if this process dies anywhere
+    // between here and the point where the new CLI owns start.lock, the lock
+    // stays live for the lease and the new CLI can still adopt it by token.
+    beginHandOff(paths.startLock, lock.token);
+    const child = spawn(process.execPath, args, { env: { ...ctx.env, [START_LOCK_ENV]: lock.token }, stdio: 'inherit' });
+    // Once spawned, start.lock lives as long as the new CLI, even if this
+    // process dies before its supervisor claims the home.
+    if (child.pid)
+        handOffFileLock(paths.startLock, lock.token, child.pid);
+    const claimed = setInterval(() => { if (readRun(ctx.paths))
+        lock.release(); }, 200);
+    const forward = (signal) => () => child.kill(signal);
+    const onInt = forward('SIGINT');
+    const onTerm = forward('SIGTERM');
+    process.on('SIGINT', onInt);
+    process.on('SIGTERM', onTerm);
+    return new Promise(resolve => {
+        child.once('error', error => {
+            clearInterval(claimed);
+            ctx.io.stderr(`botmancers: could not run ${pending}: ${error.message}\n`);
+            resolve(PRODUCT_EXIT.childFailed);
+        });
+        child.once('exit', (code, signal) => {
+            clearInterval(claimed);
+            process.off('SIGINT', onInt);
+            process.off('SIGTERM', onTerm);
+            resolve(code ?? (signal ? PRODUCT_EXIT.childFailed : PRODUCT_EXIT.ok));
+        });
+    });
+}
+// Re-checks identity each round, so a reaped-and-recycled PID counts as gone.
+async function waitGone(record, names, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const left = targetsOf(record).filter(target => names.includes(target.name) && target.owner === 'owned');
+        if (!left.length || Date.now() >= deadline)
+            return left;
+        await sleep(150);
+    }
+}
+export async function stop(ctx) {
+    const record = readRun(ctx.paths);
+    if (!record) {
+        if (existsSync(ctx.paths.runFile))
+            rmSync(ctx.paths.runFile, { force: true });
+        ctx.io.stdout(`botmancers: not running (home ${ctx.paths.home}).\n`);
+        return PRODUCT_EXIT.ok;
+    }
+    const targets = targetsOf(record);
+    const owned = targets.filter(target => target.owner === 'owned');
+    const unverified = targets.filter(target => target.owner === 'unverified');
+    if (!owned.length && !unverified.length) {
+        rmSync(ctx.paths.runFile, { force: true });
+        ctx.io.stdout(`botmancers: not running; removed stale run metadata (supervisor pid ${record.supervisor.pid} is gone).\n`);
+        return PRODUCT_EXIT.ok;
+    }
+    // The supervisor stops its children; orphans (supervisor gone) are signalled directly.
+    const supervisorAlive = owned.some(target => target.name === 'supervisor');
+    for (const { name, pid } of owned) {
+        if (name === 'supervisor' || !supervisorAlive) {
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch { /* already gone */ }
+        }
+    }
+    const names = owned.map(target => target.name);
+    let survivors = await waitGone(record, names, 15_000);
+    if (survivors.length) {
+        for (const { pid } of survivors) {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch { /* already gone */ }
+        }
+        survivors = await waitGone(record, names, 3000);
+    }
+    const remaining = [...survivors, ...unverified];
+    if (remaining.length) {
+        // Keep the ownership record (the supervisor may have removed it on its way
+        // out) so status reports the survivors and a later stop can retry.
+        writeRun(ctx.paths, owned.length ? { ...record, state: 'stopping' } : record);
+        if (survivors.length)
+            ctx.io.stderr(`botmancers: could not stop ${survivors.map(({ name, pid }) => `${name} (pid ${pid})`).join(', ')}.\n`);
+        if (unverified.length)
+            ctx.io.stderr(`botmancers: ${unverifiedNote(unverified)}. If they are not botmancers, remove ${ctx.paths.runFile}.\n`);
+        ctx.io.stderr(`botmancers: run metadata kept in ${ctx.paths.runFile}; retry with botmancers stop.\n`);
+        return PRODUCT_EXIT.degraded;
+    }
+    rmSync(ctx.paths.runFile, { force: true });
+    ctx.io.stdout(`botmancers: stopped (${owned.map(({ name, pid }) => `${name} pid ${pid}`).join(', ')}).\n`);
+    return PRODUCT_EXIT.ok;
+}
+function onPath(command, env) {
+    const exts = process.platform === 'win32' ? (env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';') : [''];
+    for (const dir of (env.PATH ?? '').split(delimiter).filter(Boolean)) {
+        for (const ext of exts) {
+            const candidate = join(dir, command + ext);
+            try {
+                accessSync(candidate, fsConstants.X_OK);
+                if (statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch { /* keep looking */ }
+        }
+    }
+    return null;
+}
+async function reachable(url) {
+    try {
+        await fetch(url, { signal: AbortSignal.timeout(1500), redirect: 'manual' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function doctor(ctx) {
+    const checks = [];
+    const add = (level, name, detail) => checks.push([level, name, detail]);
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major < 20 || (major === 20 && minor < 9))
+        add('fail', 'node', `Node ${process.version} is too old; the UI/core needs Node 20.9 or newer (22+ recommended).`);
+    else if (major < 22)
+        add('warn', 'node', `Node ${process.version}: the bundled better-sqlite3 declares Node 22+; the native check below decides.`);
+    else
+        add('ok', 'node', `Node ${process.version}`);
+    const missing = missingAppFiles(ctx.appDir);
+    const build = readBuildInfo(ctx.appDir);
+    if (missing.length)
+        add('fail', 'assets', `packaged app at ${ctx.appDir} is missing ${missing.join(', ')}; reinstall botmancers.`);
+    else if (build?.version !== ctx.version)
+        add('fail', 'assets', `packaged app is version ${build?.version ?? 'unknown'}, CLI is ${ctx.version}; reinstall botmancers.`);
+    else
+        add('ok', 'assets', `packaged UI/core ${build.version} (commit ${build.commit.slice(0, 12)})`);
+    const report = managedReport(ctx.env);
+    add('info', 'install', `${report.install.kind} (${report.install.cliPath})`);
+    if (report.install.kind === 'managed' && !report.launcher)
+        add('warn', 'launcher', `${report.paths.launcher} is missing or modified; re-run botmancers install --to ${report.current ?? ctx.version}.`);
+    if (report.shadowedBy)
+        add('warn', 'path', `\`botmancers\` on PATH resolves to ${report.shadowedBy}, not the managed launcher ${report.paths.launcher}; put ${report.paths.localBin} first on PATH (or botmancers install --purge-global).`);
+    else if (report.launcher && !report.resolved)
+        add('warn', 'path', `${report.paths.localBin} is not on PATH; add it: export PATH="${report.paths.localBin}:$PATH"`);
+    else if (report.resolved)
+        add('ok', 'path', `PATH resolves botmancers to ${report.resolved}`);
+    if (report.current || report.pending) {
+        add('info', 'versions', `cli ${ctx.version}, current ${report.current ?? '-'}${report.pending ? `, pending ${report.pending} (staged, not running; activates at the next botmancers start after ${RESTART_ACTION.split(' && ')[0]})` : ''}`);
+    }
+    if (report.install.kind === 'managed') {
+        const when = report.state.checkedAt ? `last check ${report.state.checkedAt}${report.state.latest ? `, npm latest ${report.state.latest}` : ''}` : 'not checked yet';
+        if (!report.autoupdate)
+            add('info', 'updater', 'automatic updates disabled (BOTMANCERS_DISABLE_AUTOUPDATER); botmancers upgrade still works');
+        else if (report.state.lastError)
+            add('warn', 'updater', `${when}; ${report.state.lastError}`);
+        else
+            add('ok', 'updater', `automatic updates on (${when})`);
+    }
+    if (!existsSync(ctx.paths.home)) {
+        add('fail', 'home', `${ctx.paths.home} does not exist; run botmancers setup.`);
+    }
+    else {
+        const unwritable = homeWritable(ctx.paths);
+        const mode = modeOf(ctx.paths.home);
+        if (unwritable === 'ENOENT')
+            add('fail', 'home', `${ctx.paths.home} is not fully set up; run botmancers setup.`);
+        else if (unwritable)
+            add('fail', 'home', `${ctx.paths.home} is not writable (${unwritable}).`);
+        else if (mode !== null && (mode & 0o077) !== 0)
+            add('warn', 'home', `${ctx.paths.home} is readable by others (mode ${mode.toString(8)}); run botmancers setup to restore owner-only.`);
+        else
+            add('ok', 'home', `${ctx.paths.home} is owner-only and writable`);
+    }
+    const credentials = credentialState(ctx.paths);
+    if (!credentials.ok)
+        add('fail', 'config', `${credentials.problems.join('; ')}; run botmancers setup.`);
+    else {
+        const loose = [ctx.paths.coreEnv, ctx.paths.bridgeEnv].filter(path => ((modeOf(path) ?? 0) & 0o077) !== 0);
+        if (loose.length)
+            add('fail', 'config', `${loose.join(', ')} readable by others; run botmancers setup.`);
+        else
+            add('ok', 'config', 'core.env and bridge.env are owner-only; the core lists the digest of the bridge service token');
+    }
+    if (!missing.includes('node_modules/better-sqlite3/package.json')) {
+        try {
+            execFileSync(process.execPath, ['-e', `const D=require(${JSON.stringify(join(ctx.appDir, 'node_modules/better-sqlite3'))});new D(':memory:').prepare('select 1').get()`], { cwd: ctx.appDir, stdio: ['ignore', 'ignore', 'pipe'], timeout: 15_000 });
+            add('ok', 'native', `better-sqlite3 loads on ${process.platform}-${process.arch}`);
+        }
+        catch (error) {
+            const message = String(error.stderr ?? '').split('\n').find(line => /Error/.test(line)) ?? 'load failed';
+            add('fail', 'native', `better-sqlite3 does not load on ${process.platform}-${process.arch}: ${message.trim().slice(0, 200)}`);
+        }
+    }
+    const view = await inspect(ctx);
+    if (view.record)
+        add('info', 'running', `core ${view.core?.version ?? 'unknown'}, bridge ${view.bridge?.version ?? 'unknown'} (started by ${view.record.version})`);
+    if (view.state === 'healthy')
+        add('ok', 'product', `running and healthy: UI ${view.record.ui.url}, MCP ${view.record.mcp.url}${report.pending && report.autoupdate ? `; restart to activate ${report.pending}: ${RESTART_ACTION}` : ''}`);
+    else if (view.state === 'degraded')
+        add('fail', 'product', `running but degraded: ${view.problems.join('; ')}; fix: ${RESTART_ACTION}`);
+    else {
+        const busy = [];
+        for (const port of [ctx.uiPort, ctx.mcpPort])
+            if (!(await portFree(port)))
+                busy.push(String(port));
+        if (busy.length)
+            add('fail', 'ports', `port${busy.length > 1 ? 's' : ''} ${busy.join(' and ')} on ${PRODUCT_HOST} ${busy.length > 1 ? 'are' : 'is'} in use by another process; botmancers start would fail.`);
+        else
+            add('ok', 'ports', `${PRODUCT_HOST}:${ctx.uiPort} and ${PRODUCT_HOST}:${ctx.mcpPort} are free (product stopped)`);
+    }
+    const core = { ...(readEnvFile(ctx.paths.coreEnv) ?? {}), ...ctx.env };
+    if ((core.HERMES_API_SERVER_KEY ?? '').trim())
+        add('ok', 'hermes', `HERMES_API_SERVER_KEY is configured (gateway ${core.HERMES_BASE_URL?.trim() || 'http://127.0.0.1:8642'})`);
+    else
+        add('warn', 'hermes', `Hermes is not configured: conversational turns post a Hermes error until HERMES_API_SERVER_KEY is set in ${ctx.paths.coreEnv}.`);
+    const deckUrl = (ctx.env[AGENT_DECK_URL_ENV] ?? '').trim() || DEFAULT_AGENT_DECK_URL;
+    const deckBin = onPath('agent-deck', ctx.env);
+    if (!deckBin)
+        add('warn', 'agent-deck', 'Agent Deck is unavailable: `agent-deck` is not on PATH; coding-agent runs cannot launch.');
+    else if (!(await reachable(deckUrl)))
+        add('warn', 'agent-deck', `Agent Deck is unavailable: ${deckBin} found, but its server at ${deckUrl} is not answering.`);
+    else if (!(core.AGENT_DECK_RUN_TOKEN ?? '').trim())
+        add('warn', 'agent-deck', `Agent Deck is reachable at ${deckUrl}, but AGENT_DECK_RUN_TOKEN is not set in ${ctx.paths.coreEnv}.`);
+    else
+        add('ok', 'agent-deck', `agent-deck on PATH, server ${deckUrl} reachable, run token configured`);
+    // MCP clients connected by `setup --client` and their skill (optional: only warn).
+    for (const [level, name, detail] of clientDoctorLines(ctx.env, ctx.paths, mcpTarget(ctx.paths, ctx.mcpPort)))
+        add(level, name, detail);
+    const failures = checks.filter(([level]) => level === 'fail').length;
+    const warnings = checks.filter(([level]) => level === 'warn').length;
+    const lines = [`botmancers doctor ${ctx.version} (home ${ctx.paths.home})`];
+    for (const [level, name, detail] of checks)
+        lines.push(`  ${level.padEnd(5)} ${name.padEnd(11)} ${detail}`);
+    lines.push(failures ? `result: FAILED (${failures} problem${failures > 1 ? 's' : ''}, ${warnings} warning${warnings === 1 ? '' : 's'})` : `result: ok (${warnings} warning${warnings === 1 ? '' : 's'})`);
+    ctx.io.stdout(`${lines.join('\n')}\n`);
+    return failures ? PRODUCT_EXIT.degraded : PRODUCT_EXIT.ok;
+}