tinybeeai 0.0.0-stage → 0.16.1

package/dist/connect/aivision-local.js

@@ -0,0 +1,833 @@
+// AI-Vision on this machine (KAT-82): finds a running AI-Vision server and a local checkout, connects
+// to a running server without input, starts the server from the checkout on request, and attaches
+// the AI-Vision MCP preset and vision tests to dots that made no choice of their own.
+//
+// A detected server lives in runtime values (setRuntimeValue), so it never overrides a URL the user
+// saved or set in the environment, and it disappears when the server stops answering.
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { ROOT, config, log, setting, settingSource } from '../config.js';
+import { isLoopbackHost, resolveListenHost } from '../loopback.js';
+import { getConnection, listConnections, createConnection } from '../connections/store.js';
+import { connectionFromPreset, presetOf } from '../connections/presets.js';
+import { refreshConnection } from '../connections/manager.js';
+import { list, update } from '../db.js';
+import { aivisionTokenFor, originOf, setManagedTokenSource, tokenForManagedStart, TOKEN_KEY } from './aivision-token.js';
+import { fetchT } from './deps.js';
+import { getMeta, runtimeValue, setMeta, setRuntimeValue, storedValue } from './store.js';
+export const SERVER_ENTRY = 'apps/playground/demo/aivision-server.mts';
+export const MCP_ENTRY = 'apps/playground/demo/veesan-mcp.mts';
+// Tests set LOCALDOST_AIVISION_DEFAULT_PORT to a closed port, so a real AI-Vision server on the same machine
+// (the self-hosted CI runner has one on 5880) never answers their probes.
+export const DEFAULT_PORT = ((p) => (Number.isInteger(p) && p > 0 && p < 65536 ? p : 5880))(Number(process.env.LOCALDOST_AIVISION_DEFAULT_PORT));
+/** AI-Vision always runs on this model, whatever the dot's Codex model or an inherited VEESAN_MODEL_NAME says. */
+export const AIVISION_MODEL = 'gpt-5.6-luna';
+const RECHECK_MS = 3 * 60_000;
+const PROBE_TIMEOUT_MS = 2500;
+const START_TIMEOUT_MS = 120_000;
+const LOG_LINES = 200;
+/** lsof lists the listening pids on the port, ps gives each its group. macOS and Linux. */
+function lsofListeners(port) {
+    if (process.platform === 'win32')
+        return undefined;
+    const run = (cmd, args) => {
+        try {
+            return execFileSync(cmd, args, { encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] });
+        }
+        catch (err) {
+            // lsof exits 1 with no output when nothing listens: that is an answer, not a failure.
+            const e = err;
+            return e.status === 1 && !e.code && !(e.stdout ?? '').trim() ? '' : undefined;
+        }
+    };
+    const out = run('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t']);
+    if (out === undefined)
+        return undefined;
+    const pids = [...new Set(out.split(/\s+/).filter(Boolean).map(Number))];
+    if (pids.some((n) => !Number.isInteger(n) || n <= 0))
+        return undefined;
+    const procs = [];
+    for (const pid of pids) {
+        const pgid = Number(run('ps', ['-o', 'pgid=', '-p', String(pid)])?.trim());
+        if (!Number.isInteger(pgid) || pgid <= 0)
+            return undefined;
+        procs.push({ pid, pgid });
+    }
+    return procs;
+}
+const defaultHooks = {
+    home: () => homedir(),
+    localdostRoot: () => ROOT,
+    // detached: the server and the processes npx starts share one group, so stop() can end them all.
+    spawn: (cmd, args, opts) => spawn(cmd, args, { cwd: opts.cwd, env: opts.env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] }),
+    platform: () => process.platform,
+    exists: (p) => existsSync(p),
+    listeners: lsofListeners,
+};
+const hooks = { ...defaultHooks };
+/** Test hook: override some hooks, or reset all with no argument. */
+export function setLocalHooks(patch) {
+    Object.assign(hooks, patch ? patch : defaultHooks);
+}
+let local = {};
+let child;
+let logLines = [];
+let timer;
+let inflight;
+let lastRun = 0;
+let auto = false;
+// ---------- detection ----------
+function normalizeUrl(raw) {
+    try {
+        const u = new URL((raw ?? '').trim());
+        if ((u.protocol !== 'http:' && u.protocol !== 'https:') || u.username || u.password)
+            return undefined;
+        return `${u.origin}${u.pathname.replace(/\/+$/, '')}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Where a server may listen: AIVISION_PORT, then VEESAN_ENGINE_URL, then the default port. */
+export function candidateUrls() {
+    const out = [];
+    const port = Number(setting('AIVISION_PORT'));
+    if (Number.isInteger(port) && port > 0 && port < 65536)
+        out.push(`http://127.0.0.1:${port}`);
+    const engine = normalizeUrl(setting('VEESAN_ENGINE_URL'));
+    if (engine)
+        out.push(engine);
+    out.push(`http://127.0.0.1:${DEFAULT_PORT}`);
+    return [...new Set(out)];
+}
+/** The server localdost started, the token it got, and the origin that token is bound to. */
+let managedToken;
+/** True while the process group localdost started still runs. A server that replaced it on the port is not it. */
+function managedAlive() {
+    const proc = child;
+    if (!proc || !local.managed)
+        return undefined;
+    return (proc.exitCode === null && proc.signalCode === null) || groupAlive(proc) ? proc : undefined;
+}
+/**
+ * True only when every process LISTENING on the managed port belongs to the process group localdost
+ * started. A live group is not enough: the child can close its listener and another program bind the
+ * same port, and that program must get no credentials. Anything unclear (nothing listens, lsof
+ * fails, a foreign pid) counts as foreign.
+ */
+function managedOwnsPort(proc) {
+    const port = Number(new URL(local.managed?.url ?? 'http://invalid').port);
+    if (!proc.pid || !Number.isInteger(port) || port <= 0)
+        return false;
+    const procs = hooks.listeners(port);
+    return !!procs && procs.length > 0 && procs.every((l) => l.pgid === proc.pid);
+}
+setManagedTokenSource(() => {
+    const m = managedToken;
+    if (!m || managedAlive() !== m.proc)
+        return undefined;
+    const { proc, token } = m;
+    // The token is read only when a request to this origin asks for it, and the listener is checked then.
+    return {
+        origin: m.origin,
+        get token() {
+            return managedAlive() === proc && managedOwnsPort(proc) ? token : '';
+        },
+    };
+});
+/** True when localdost started the server at this address itself, it still runs, and it still holds the port. */
+export function isManagedUrl(url) {
+    const proc = managedAlive();
+    return !!proc && !!originOf(url) && originOf(local.managed?.url) === originOf(url) && managedOwnsPort(proc);
+}
+async function healthOnce(url, token) {
+    // No redirects: a token header never follows to another host.
+    // platform=web: localdost runs web vision tests, so checks for desktop or Android modes do not count.
+    return fetchT(`${url}/aivision/health?platform=web`, { redirect: 'manual', headers: token ? { 'x-veesan-internal': token } : {} }, PROBE_TIMEOUT_MS);
+}
+/**
+ * One health check. Undefined when nothing that looks like AI-Vision answers. The token comes from
+ * aivisionTokenFor only: a detected address is never bound, so it gets none.
+ */
+export async function probeServer(url) {
+    try {
+        // Ask without credentials first; the token goes only to a server that asked for sign-in.
+        let res = await healthOnce(url, undefined);
+        if (res.status === 401 || res.status === 403) {
+            const token = aivisionTokenFor(url);
+            if (token)
+                res = await healthOnce(url, token);
+            if (res.status === 401 || res.status === 403)
+                return { url, needsToken: true };
+        }
+        // A 5xx that still answers as AI-Vision is a server with a failed check, not a missing one.
+        if (!res.ok && res.status < 500)
+            return undefined;
+        const body = (await res.json().catch(() => undefined));
+        if (!body || typeof body !== 'object' || (!Array.isArray(body.checks) && typeof body.ok !== 'boolean'))
+            return undefined;
+        // On an error status only the full health shape counts: a gateway's `{ ok: false }` is not AI-Vision.
+        if (!res.ok && !Array.isArray(body.checks))
+            return undefined;
+        const out = { url };
+        if (typeof body.version === 'string' && body.version)
+            out.version = body.version.slice(0, 40);
+        const failed = (Array.isArray(body.checks) ? body.checks : [])
+            .filter((c) => !!c && typeof c === 'object' && c.ok === false)
+            .map((c) => (typeof c.id === 'string' ? c.id.slice(0, 40) : 'check'))
+            .slice(0, 10);
+        if (!res.ok || body.ok === false || body.healthy === false || failed.length) {
+            out.unhealthy = true;
+            if (failed.length)
+                out.failedChecks = failed;
+        }
+        return out;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isCheckout(dir) {
+    return !!dir && path.isAbsolute(dir) && hooks.exists(path.join(dir, SERVER_ENTRY));
+}
+function aivisionDirs(parent, all) {
+    try {
+        return readdirSync(parent, { withFileTypes: true })
+            .filter((d) => (d.isDirectory() || d.isSymbolicLink()) && (all || /aivision/i.test(d.name)))
+            .map((d) => path.join(parent, d.name))
+            .sort()
+            .slice(0, 200);
+    }
+    catch {
+        return [];
+    }
+}
+/** AIVISION_CHECKOUT, then ~/code/*aivision*, then folders next to the localdost checkout. */
+export function findCheckout() {
+    // Only a folder the user named counts here; a runtime value is this function's own earlier answer.
+    const named = userOwns('AIVISION_CHECKOUT') ? setting('AIVISION_CHECKOUT')?.trim() : undefined;
+    if (isCheckout(named))
+        return path.normalize(named).replace(/\/+$/, '');
+    const root = path.resolve(hooks.localdostRoot());
+    const candidates = [...aivisionDirs(path.join(hooks.home(), 'code'), false), ...aivisionDirs(path.dirname(root), true)];
+    return candidates.find((d) => path.resolve(d) !== root && isCheckout(d));
+}
+function checkoutVersion(dir) {
+    if (!dir)
+        return undefined;
+    try {
+        const v = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8')).version;
+        return typeof v === 'string' ? v.slice(0, 40) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when the user chose the value (saved on Setup or set in the environment). */
+function userOwns(key) {
+    return settingSource(key) === 'env' || storedValue(key)?.value !== undefined;
+}
+/** Probes, finds the checkout, and updates the runtime values. Runs one at a time. */
+export function refreshLocal(opts = {}) {
+    if (inflight)
+        return inflight;
+    if (!opts.force && Date.now() - lastRun < 5000)
+        return Promise.resolve(local);
+    inflight = (async () => {
+        try {
+            reapChild();
+            const checkout = findCheckout();
+            let server;
+            // The first server that lets localdost in wins; one that asks for sign-in is kept only as a fallback.
+            let locked;
+            for (const url of candidateUrls()) {
+                const found = await probeServer(url);
+                if (found && !found.needsToken && !found.unhealthy) {
+                    server = found;
+                    break;
+                }
+                locked ??= found;
+            }
+            server ??= locked;
+            if (server && !server.version) {
+                const v = checkoutVersion(checkout);
+                if (v)
+                    server.version = v;
+            }
+            const next = { checkedAt: new Date().toISOString() };
+            if (server)
+                next.server = server;
+            if (checkout)
+                next.checkout = checkout;
+            if (local.managed)
+                next.managed = local.managed;
+            local = next;
+            // A server that refuses localdost (sign-in needed, no working token) or reports a failed check is
+            // shown, never connected.
+            const usable = server && !server.needsToken && !server.unhealthy ? server.url : null;
+            // A value the user chose always wins, so a runtime value left from earlier detection goes.
+            setRuntimeValue('AIVISION_SERVER_URL', userOwns('AIVISION_SERVER_URL') ? null : usable);
+            setRuntimeValue('AIVISION_CHECKOUT', userOwns('AIVISION_CHECKOUT') ? null : (checkout ?? null));
+            if (setting('AIVISION_SERVER_URL'))
+                autoAttach();
+            return local;
+        }
+        finally {
+            lastRun = Date.now();
+            inflight = undefined;
+        }
+    })();
+    return inflight;
+}
+export function localState() {
+    return local;
+}
+/** True when the active URL is one localdost found, not one the user entered. */
+export function detectedActive() {
+    return !userOwns('AIVISION_SERVER_URL') && !!runtimeValue('AIVISION_SERVER_URL');
+}
+export function localView() {
+    const v = { ...local, startUrl: `http://127.0.0.1:${startPort()}` };
+    // The log explains a failed start, and a managed server that runs but reports a failed check.
+    if (local.managed?.state === 'failed' || (local.managed?.state === 'running' && local.server?.unhealthy))
+        v.logTail = logLines.slice(-15);
+    const conn = aivisionConnectionId();
+    const dots = list('watches').filter((w) => !w.archived);
+    v.dots = {
+        mcp: conn ? dots.filter((w) => w.connections?.includes(conn)).length : 0,
+        cases: dots.filter((w) => w.runner?.aivision && w.runner.aivision.enabled !== false).length,
+    };
+    return v;
+}
+// ---------- background checks ----------
+/** Boot hook (src/index.ts): check now, then every few minutes. Tests never call it. */
+export function startLocalChecks() {
+    auto = true;
+    void refreshLocal({ force: true }).catch((err) => log.warn('aivision: detection failed', String(err)));
+    if (!timer) {
+        timer = setInterval(() => void refreshLocal({ force: true }).catch(() => undefined), RECHECK_MS);
+        timer.unref();
+    }
+}
+/** Setup load: re-check when the background checks run. */
+export function refreshOnView() {
+    return auto ? refreshLocal() : undefined;
+}
+// ---------- managed server ----------
+const ENV_ALLOW = [
+    /^(HOME|PATH|USER|LOGNAME|SHELL|LANG|TERM|TMPDIR|TZ|TMP|TEMP)$/,
+    /^LC_/,
+    /^XDG_(CONFIG|DATA|CACHE|STATE)_HOME$/,
+    /^(HTTPS_PROXY|HTTP_PROXY|NO_PROXY|https_proxy|http_proxy|no_proxy|NODE_EXTRA_CA_CERTS|SSL_CERT_FILE|SSL_CERT_DIR)$/,
+    /^(VEESAN|AIVISION|MIDSCENE|PUPPETEER)_[A-Z0-9_]+$/,
+    /^(OPENAI_API_KEY|OPENAI_BASE_URL|CODEX_HOME)$/,
+];
+const MAC_CHROME = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+/** Allowlisted env for the server, with defaults for a Mac signed in to Codex. */
+export function serverEnv(port, src = process.env) {
+    const out = {};
+    for (const [k, v] of Object.entries(src))
+        if (v !== undefined && v !== '' && ENV_ALLOW.some((re) => re.test(k)))
+            out[k] = v;
+    // The access token goes through the gate: one saved without an address, or for this same origin.
+    delete out[TOKEN_KEY];
+    const token = tokenForManagedStart(`http://127.0.0.1:${port}`);
+    if (token)
+        out[TOKEN_KEY] = token;
+    // Values saved on the Setup page count too, for the names the allowlist passes.
+    const key = setting('OPENAI_API_KEY');
+    if (key && !out.OPENAI_API_KEY)
+        out.OPENAI_API_KEY = key;
+    out.AIVISION_PORT = String(port);
+    if (!out.VEESAN_MODEL_BASE_URL && !out.OPENAI_API_KEY)
+        out.VEESAN_MODEL_BASE_URL = 'codex://';
+    out.VEESAN_MODEL_NAME = AIVISION_MODEL;
+    if (!out.PUPPETEER_EXECUTABLE_PATH && hooks.platform() === 'darwin' && hooks.exists(MAC_CHROME))
+        out.PUPPETEER_EXECUTABLE_PATH = MAC_CHROME;
+    return out;
+}
+/** Secret values handed to the child; its log lines are cleaned of them before anyone sees them. */
+let logSecrets = [];
+/** Env names whose values are never secret; everything else the child gets is hidden in its log. */
+const SAFE_ENV = /^(PATH|HOME|USER|LOGNAME|SHELL|LANG|TERM|TMPDIR|TZ|TMP|TEMP|LC_[A-Z_]+|XDG_(CONFIG|DATA|CACHE|STATE)_HOME|AIVISION_PORT|VEESAN_MODEL_BASE_URL|VEESAN_MODEL_NAME|PUPPETEER_EXECUTABLE_PATH|NODE_EXTRA_CA_CERTS|SSL_CERT_FILE|SSL_CERT_DIR|NO_PROXY|no_proxy)$/;
+const SECRET_SHAPE = /\b(sk-[A-Za-z0-9_-]{8,}|gh[pousr]_[A-Za-z0-9]{8,}|github_pat_[A-Za-z0-9_]{8,}|xox[abpr]-[A-Za-z0-9-]{8,}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)/g;
+const AUTH_HEADER = /\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi;
+const URL_CREDENTIALS = /(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/:@]+:[^\s/@]+@/gi;
+export function redactLine(line, secrets = logSecrets) {
+    let out = line;
+    for (const v of secrets)
+        if (v.length >= 6)
+            out = out.split(v).join('[hidden]');
+    return out.replace(SECRET_SHAPE, '[hidden]').replace(AUTH_HEADER, '$1 [hidden]').replace(URL_CREDENTIALS, '$1[hidden]@');
+}
+/**
+ * Text after the last newline, per stream: a line is redacted only once it is whole, so a secret
+ * split across chunks, or with the other stream's output in between, is still caught.
+ */
+let logRest = { out: '', err: '' };
+function keepLine(line) {
+    if (line.trim())
+        logLines.push(redactLine(line).slice(0, 400));
+}
+/**
+ * Where to cut a long line without a newline: leave the last stretch, as long as the longest secret,
+ * unread, and move the cut before any secret that crosses it, so no secret is split in two pieces.
+ */
+export function safeCut(text, secrets = logSecrets) {
+    const longest = secrets.reduce((n, v) => Math.max(n, v.length), 0);
+    let cut = Math.max(0, text.length - Math.min(4000, Math.max(256, longest)));
+    const spans = [];
+    for (const v of secrets) {
+        if (v.length < 6)
+            continue;
+        for (let i = text.indexOf(v); i !== -1; i = text.indexOf(v, i + 1))
+            spans.push([i, i + v.length]);
+    }
+    for (const re of [SECRET_SHAPE, AUTH_HEADER, URL_CREDENTIALS])
+        for (const m of text.matchAll(re))
+            spans.push([m.index, m.index + m[0].length]);
+    for (const [a, b] of spans.sort((x, y) => y[0] - x[0]))
+        if (a < cut && b > cut)
+            cut = a;
+    return cut;
+}
+function pushLog(chunk, stream) {
+    const parts = (logRest[stream] + chunk).split(/\r?\n/);
+    let rest = parts.pop() ?? '';
+    for (const line of parts)
+        keepLine(line);
+    // A child that never prints a newline still has its output kept, in bounded pieces.
+    if (rest.length > 8000) {
+        const cut = safeCut(rest);
+        keepLine(rest.slice(0, cut));
+        rest = rest.slice(cut);
+    }
+    logRest[stream] = rest;
+    if (logLines.length > LOG_LINES)
+        logLines = logLines.slice(-LOG_LINES);
+}
+function flushLog() {
+    keepLine(logRest.out);
+    keepLine(logRest.err);
+    logRest = { out: '', err: '' };
+    if (logLines.length > LOG_LINES)
+        logLines = logLines.slice(-LOG_LINES);
+}
+export function managedLog() {
+    return [...logLines];
+}
+function startPort() {
+    const port = Number(setting('AIVISION_PORT'));
+    return Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_PORT;
+}
+/**
+ * Starts the server from the detected checkout as a child of localdost. Resolves once it is starting;
+ * the server connects when its health check answers. Throws with a plain message when it cannot start.
+ */
+let startInflight;
+export function startManaged() {
+    // A Stop still waiting for the old server to go holds its port: start after it.
+    if (stopInflight)
+        return stopInflight.then(() => startManaged());
+    // One start at a time, and never a second child while the first still runs.
+    reapChild();
+    if (child)
+        return Promise.resolve(local);
+    startInflight ??= doStart().finally(() => {
+        startInflight = undefined;
+    });
+    return startInflight;
+}
+/** Forgets a managed server whose launcher exited and whose process group is gone. */
+function reapChild() {
+    if (!child || (child.exitCode === null && child.signalCode === null) || groupAlive(child))
+        return;
+    child = undefined;
+    if (local.managed && local.managed.state !== 'stopped' && local.managed.state !== 'failed')
+        finish('failed', 'AI-Vision stopped.');
+}
+/** Bumped by Stop: a start still looking around when Stop came never spawns. */
+let startGen = 0;
+async function doStart() {
+    const gen = startGen;
+    const cur = await refreshLocal({ force: true });
+    if (gen !== startGen)
+        return local;
+    if (cur.server && !cur.server.unhealthy && !cur.server.needsToken)
+        return cur;
+    // A failing or sign-in server elsewhere (VEESAN_ENGINE_URL) does not stop a local start, but one
+    // that answers on the port Start would use is this one.
+    if (cur.server && (await probeServer(`http://127.0.0.1:${startPort()}`)))
+        return local;
+    if (gen !== startGen)
+        return local;
+    const checkout = cur.checkout;
+    if (!checkout)
+        throw new Error('No AI-Vision checkout was found on this Mac.');
+    if (stray && ((stray.exitCode === null && stray.signalCode === null) || groupAlive(stray))) {
+        throw new Error(`An earlier AI-Vision (process group ${stray.pid ?? 'unknown'}) is still running. Stop it by hand, then start again.`);
+    }
+    stray = undefined;
+    const port = startPort();
+    const url = `http://127.0.0.1:${port}`;
+    // Another program on the port would answer for the new server and get its token.
+    if (await portInUse(port))
+        throw new Error(`Another program uses port ${port}. Stop it, or set AIVISION_PORT to a free port.`);
+    if (gen !== startGen)
+        return local;
+    logLines = [];
+    logRest = { out: '', err: '' };
+    const childEnv = serverEnv(port);
+    // Every value handed to the child counts as secret except names known to hold none.
+    logSecrets = Object.entries(childEnv)
+        .filter(([k, v]) => v && !SAFE_ENV.test(k))
+        .map(([, v]) => v);
+    let proc;
+    try {
+        proc = hooks.spawn('npx', ['tsx', SERVER_ENTRY], { cwd: checkout, env: childEnv });
+    }
+    catch (err) {
+        throw new Error(`AI-Vision did not start: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    child = proc;
+    const sent = childEnv[TOKEN_KEY];
+    managedToken = sent ? { proc, token: sent, origin: originOf(url) } : undefined;
+    const managed = { state: 'starting', checkout, url, startedAt: new Date().toISOString() };
+    if (proc.pid)
+        managed.pid = proc.pid;
+    local = { ...local, managed };
+    proc.stdout?.setEncoding('utf8').on('data', (d) => pushLog(d, 'out'));
+    proc.stderr?.setEncoding('utf8').on('data', (d) => pushLog(d, 'err'));
+    proc.on('error', (err) => {
+        pushLog(`${String(err)}\n`, 'err');
+        flushLog();
+        // A spawn error (ENOENT) may come without an exit event: free the slot so Start works again.
+        if (child === proc)
+            child = undefined;
+        finish('failed', `AI-Vision did not start: ${err.message}`);
+    });
+    // close comes after the last output, so the tail of a line without a newline is kept too.
+    proc.on('close', () => flushLog());
+    proc.on('exit', (code, signal) => {
+        if (child !== proc)
+            return;
+        if (local.managed?.state === 'stopped') {
+            child = undefined;
+            return;
+        }
+        // npx can exit while the server it started runs on in the same group: keep the handle, so Stop
+        // and shutdown still end that group. reapChild notices when the group is gone.
+        if (groupAlive(proc)) {
+            log.info('aivision: the launcher exited; the server it started still runs');
+            // Watch the group closely, so the handle goes as soon as the group does and a reused pid is
+            // never signalled.
+            const watch = setInterval(() => {
+                if (child !== proc)
+                    clearInterval(watch);
+                else if (!groupAlive(proc)) {
+                    clearInterval(watch);
+                    reapChild();
+                    // Check again, after any check already running, so the dead server's address stops being
+                    // used now, not at the next check.
+                    void (inflight ?? Promise.resolve())
+                        .catch(() => undefined)
+                        .then(() => refreshLocal({ force: true }))
+                        .catch(() => undefined);
+                }
+            }, 1000);
+            watch.unref();
+            return;
+        }
+        child = undefined;
+        finish('failed', `AI-Vision stopped (${signal ?? `exit ${code ?? 'unknown'}`}).`);
+        void refreshLocal({ force: true }).catch(() => undefined);
+    });
+    void waitHealthy(proc, url);
+    return local;
+}
+function finish(state, error) {
+    if (!local.managed)
+        return;
+    const m = { ...local.managed, state };
+    if (error)
+        m.error = error;
+    else
+        delete m.error;
+    local = { ...local, managed: m };
+}
+async function waitHealthy(proc, url) {
+    const until = Date.now() + START_TIMEOUT_MS;
+    while (Date.now() < until && child === proc) {
+        await new Promise((r) => setTimeout(r, 1000));
+        if (child !== proc)
+            return;
+        const found = await probeServer(url);
+        // Stop may have come while the probe ran: a stopped server never turns back to running.
+        if (child !== proc)
+            return;
+        if (found && !found.unhealthy) {
+            // Connect first, then report running. A server that asks for sign-in runs, but stays unconnected
+            // until a token is saved; the sheet says so and keeps Stop.
+            await refreshLocal({ force: true });
+            if (child === proc)
+                finish('running');
+            return;
+        }
+        if (found && local.managed?.state === 'starting') {
+            // It answers, with a failed check (warming up, for example): running, with Stop, and polled on
+            // until it passes, so it connects as soon as it does.
+            await refreshLocal({ force: true });
+            if (child === proc)
+                finish('running');
+        }
+    }
+    if (child === proc && local.managed?.state === 'starting') {
+        finish('failed', 'AI-Vision did not answer within 2 minutes.');
+        // A server that outlives the kill blocks the next Start, as after a failed Stop.
+        // Start waits for this cleanup, as it waits for a Stop.
+        const cleanup = stopChild(proc)
+            .then((gone) => {
+            if (!gone)
+                stray = proc;
+            return gone;
+        })
+            .finally(() => {
+            if (stopInflight === cleanup)
+                stopInflight = undefined;
+        });
+        stopInflight = cleanup;
+    }
+}
+/** True when something accepts a connection on the loopback port. */
+function portInUse(port) {
+    return new Promise((resolve) => {
+        const sock = connect({ host: '127.0.0.1', port });
+        const done = (used) => {
+            sock.destroy();
+            resolve(used);
+        };
+        sock.setTimeout(PROBE_TIMEOUT_MS, () => done(true));
+        sock.once('connect', () => done(true));
+        sock.once('error', () => done(false));
+    });
+}
+/** The group outlives its leader while any process in it runs. */
+function groupAlive(proc) {
+    if (!proc.pid)
+        return false;
+    try {
+        process.kill(-proc.pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * SIGTERM to the whole process group, SIGKILL to the group after 3 seconds. Resolves true once every
+ * process in the group is gone (npx can exit before the server it started), false after 5 seconds.
+ */
+function stopChild(proc) {
+    const kill = (sig) => {
+        try {
+            if (proc.pid)
+                process.kill(-proc.pid, sig);
+            else
+                proc.kill(sig);
+        }
+        catch {
+            try {
+                proc.kill(sig);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    };
+    const exited = () => proc.exitCode !== null || proc.signalCode !== null;
+    const gone = () => exited() && !groupAlive(proc);
+    if (gone())
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        const startedAt = Date.now();
+        let hard = false;
+        kill('SIGTERM');
+        const tick = setInterval(() => {
+            if (gone()) {
+                clearInterval(tick);
+                resolve(true);
+                return;
+            }
+            const waited = Date.now() - startedAt;
+            if (!hard && waited >= 3000) {
+                hard = true;
+                kill('SIGKILL');
+            }
+            if (waited >= 5000) {
+                clearInterval(tick);
+                resolve(false);
+            }
+        }, 50);
+    });
+}
+/** Stops a server localdost started. A server started elsewhere is left alone. */
+/** Set while Stop waits for the old server's processes to go; a Start waits for it. */
+let stopInflight;
+/** A server Stop could not end. Start refuses while its process group still runs. */
+let stray;
+export async function stopManaged() {
+    startGen++;
+    const pending = startInflight;
+    if (pending && !child)
+        await pending.catch(() => undefined);
+    const proc = child;
+    if (!proc) {
+        // A second Stop while the first still waits returns once the first is done.
+        if (stopInflight)
+            await stopInflight;
+        return local;
+    }
+    finish('stopped');
+    const run = local.managed;
+    child = undefined;
+    // Wait until it is gone, so shutdown does not exit before the kill lands.
+    const stopping = stopChild(proc).finally(() => {
+        if (stopInflight === stopping)
+            stopInflight = undefined;
+    });
+    stopInflight = stopping;
+    const gone = await stopping;
+    // Start waits for this Stop, so the run is still the one stopped; check anyway.
+    if (local.managed !== run)
+        return local;
+    if (!gone) {
+        const pid = proc.pid ? ` (process group ${proc.pid})` : '';
+        log.warn(`aivision: the managed server did not stop${pid}`);
+        stray = proc;
+        finish('failed', `AI-Vision did not stop within 5 seconds${pid}. Stop it by hand.`);
+        return local;
+    }
+    // A check that probed the server before it went would set its address and server again after
+    // this cleanup: let it land first, so Stop has the last word.
+    if (inflight)
+        await inflight.catch(() => undefined);
+    if (detectedActive() && runtimeValue('AIVISION_SERVER_URL') === local.managed?.url)
+        setRuntimeValue('AIVISION_SERVER_URL', null);
+    local = { ...local };
+    delete local.server;
+    return local;
+}
+/** Shutdown hook: stop the managed server and the timer. */
+export async function shutdownLocal() {
+    if (timer)
+        clearInterval(timer);
+    timer = undefined;
+    auto = false;
+    await stopManaged();
+}
+// ---------- auto-attach ----------
+function aivisionConnectionId() {
+    return listConnections().find((c) => c.preset === 'aivision')?.id;
+}
+let stdioSkipLogged = false;
+/**
+ * Background detection has no request to judge, so it applies the same rule the manual routes do
+ * for a stdio connection (it runs a command on this machine): a token is set, LOCALDOST_ALLOW_STDIO=1,
+ * or the server listens on loopback only. A HOST that resolveListenHost refuses counts as open to
+ * the network.
+ */
+function stdioAllowedInBackground() {
+    if (config.token || process.env.LOCALDOST_ALLOW_STDIO === '1')
+        return true;
+    try {
+        return isLoopbackHost(resolveListenHost(config.host, config.token));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * For every dot without an explicit choice: attaches the AI-Vision MCP preset, and turns on vision
+ * tests when the dot has a repo and a base URL. Each dot is handled once per kind, so a choice the
+ * user makes afterwards (detach, turn off) stays.
+ */
+export function autoAttach() {
+    const done = { mcp: [], cases: [] };
+    const meta = getMeta('aivision');
+    const seen = { ...(meta.autoDots ?? {}) };
+    let connId = aivisionConnectionId();
+    const checkout = setting('AIVISION_CHECKOUT')?.trim();
+    if (!connId && checkout && hooks.exists(path.join(checkout, MCP_ENTRY))) {
+        if (!stdioAllowedInBackground()) {
+            // Creating it would run a command from background detection, past the gate the manual routes enforce.
+            if (!stdioSkipLogged) {
+                stdioSkipLogged = true;
+                log.info('aivision: AI-Vision MCP connection not created: it runs a command, and stdio needs LOCALDOST_TOKEN, LOCALDOST_ALLOW_STDIO=1, or a loopback-only server');
+            }
+        }
+        else {
+            const { input } = connectionFromPreset('aivision', { checkout });
+            if (input) {
+                const conn = createConnection(input);
+                connId = conn.id;
+                void refreshConnection(conn.id).catch(() => undefined);
+            }
+        }
+    }
+    let changed = false;
+    for (const w of list('watches')) {
+        if (w.archived)
+            continue;
+        const handled = new Set(seen[w.id] ?? []);
+        const patch = {};
+        if (connId && !handled.has('mcp')) {
+            const has = (w.connections ?? []).some((id) => presetOf(getConnection(id))?.id === 'aivision');
+            if (!has) {
+                patch.connections = [...(w.connections ?? []), connId];
+                done.mcp.push(w.id);
+            }
+            handled.add('mcp');
+        }
+        if (!handled.has('cases') && w.repo && w.baseUrl) {
+            if (!w.runner?.aivision) {
+                patch.runner = { ...w.runner, aivision: { backend: 'server', enabled: true } };
+                done.cases.push(w.id);
+            }
+            handled.add('cases');
+        }
+        if (Object.keys(patch).length)
+            update('watches', w.id, { ...patch, updatedAt: new Date().toISOString() });
+        if (handled.size !== (seen[w.id]?.length ?? 0)) {
+            seen[w.id] = [...handled].sort();
+            changed = true;
+        }
+    }
+    if (changed)
+        setMeta('aivision', { autoDots: seen });
+    if (done.mcp.length || done.cases.length)
+        log.info(`aivision: attached to ${done.mcp.length} dot(s), vision tests on for ${done.cases.length} dot(s)`);
+    return done;
+}
+/** Test hook: forget the detection state. */
+export function resetLocal() {
+    local = {};
+    stdioSkipLogged = false;
+    logLines = [];
+    lastRun = 0;
+    inflight = undefined;
+    if (timer)
+        clearInterval(timer);
+    timer = undefined;
+    auto = false;
+    child = undefined;
+    managedToken = undefined;
+    startInflight = undefined;
+    stopInflight = undefined;
+    stray = undefined;
+    setRuntimeValue('AIVISION_SERVER_URL', null);
+    setRuntimeValue('AIVISION_CHECKOUT', null);
+}
+//# sourceMappingURL=aivision-local.js.map