@lovinka/vitrinka 1.21.0 → 1.22.0

package/dist/cli.js

@@ -11,7 +11,7 @@
 // `--key`, repeatable `--chip`). gallery.mjs is now a passthrough shim to this file.
 // Design: vitrinka/docs/plans/2026-07-03-hand-in-hand-tooling-design.md
 import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, renameSync, readdirSync, copyFileSync, mkdtempSync, chmodSync, appendFileSync, statSync, openSync, readSync, closeSync, realpathSync, openAsBlob, lstatSync, constants as fsConstants, } from 'node:fs';
-import { join, resolve, basename, dirname, extname, relative, sep, isAbsolute } from 'node:path';
+import { join, resolve, basename, dirname, extname, relative, sep, isAbsolute, delimiter } from 'node:path';
 import { tmpdir, hostname } from 'node:os';
 import { spawnSync, spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
@@ -1597,9 +1597,91 @@ async function doctorCmd(args) {
     }
     const appPath = refreshDesktopAppFlag();
     console.log(appPath ? `✓ app        ${appPath} (flag: ${desktopAppFlagPath()})` : `- app        Vitrinka.app not installed (no flag)`);
+    if (reachable && token)
+        await doctorListenersRow(base, token, fix);
     if (failed)
         process.exit(1);
 }
+// staleLocalLeases splits this host's leases into live and stale (PURE apart
+// from the liveness probe, which is injected — unit-tested). A lease is stale
+// when its owning pid is gone from THIS machine: the watch process died without
+// releasing (SIGKILL, panic, an OS restart that outlived the server's memory).
+// Leases from other hosts are never judged — we cannot see their process table.
+export function staleLocalLeases(leases, host, pidAlive) {
+    const stale = [];
+    let live = 0;
+    for (const l of leases) {
+        const session = String(l.session ?? '');
+        const cut = session.lastIndexOf(':');
+        if (cut < 0 || session.slice(0, cut) !== host)
+            continue; // another machine
+        const pid = Number(session.slice(cut + 1));
+        if (!Number.isInteger(pid) || pid <= 0)
+            continue; // unparseable — leave it alone
+        if (pidAlive(pid))
+            live += 1;
+        else
+            stale.push(l);
+    }
+    return { stale, live };
+}
+// pidAlive: signal 0 probes existence without delivering anything. EPERM means
+// the pid exists but belongs to another user — alive, just not ours.
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+// doctorListenersRow reports this machine's work-queue leases and, with --fix,
+// releases the ones whose watch process is gone. A stale lease is not cosmetic:
+// it holds the board's scope, so the next session to arm a listener from
+// ANOTHER machine is refused (409 "live, another machine") until it clears.
+async function doctorListenersRow(base, token, fix) {
+    const headers = { Authorization: `Bearer ${token}` };
+    let leases;
+    try {
+        const res = await fetch(`${base}/api/v1/work/listeners`, { headers, signal: AbortSignal.timeout(10_000) });
+        if (!res.ok) {
+            console.log(`? listeners  check failed (HTTP ${res.status})`);
+            return;
+        }
+        leases = (await res.json())?.listeners ?? [];
+    }
+    catch (e) {
+        console.log(`? listeners  check failed (${e instanceof Error ? e.message : String(e)})`);
+        return;
+    }
+    const { stale, live } = staleLocalLeases(leases, hostname(), pidAlive);
+    if (stale.length === 0) {
+        console.log(`✓ listeners  ${live} live on this machine, no stale leases`);
+        return;
+    }
+    const label = (l) => l.scope || l.scopeKind || '?';
+    if (!fix) {
+        console.log(`✗ listeners  ${stale.length} stale lease${stale.length > 1 ? 's' : ''} held by dead watch processes — repair: vitrinka doctor --fix`);
+        for (const l of stale)
+            console.log(`             ${label(l)} (session ${l.session})`);
+        return;
+    }
+    let released = 0;
+    for (const l of stale) {
+        try {
+            const res = await fetch(`${base}/api/v1/work/listeners/${l.id}`, { method: 'DELETE', headers, signal: AbortSignal.timeout(10_000) });
+            if (res.ok || res.status === 404)
+                released += 1;
+            else
+                console.log(`             ${label(l)}: release failed (HTTP ${res.status})`);
+        }
+        catch (e) {
+            console.log(`             ${label(l)}: release failed (${e instanceof Error ? e.message : String(e)})`);
+        }
+    }
+    console.log(`✓ listeners  released ${released}/${stale.length} stale lease${stale.length > 1 ? 's' : ''} (${live} live)`);
+}
 // ---------- install: PATH shim ----------
 // ---------- plugin distribution (skills ship via the runtimes' plugin systems) ----------
 // The skills bundle used to be copied into ~/.claude/skills (install-skills,
@@ -1654,13 +1736,9 @@ function installPluginInto(rt) {
     }
     return true;
 }
-// updatePluginIn refreshes an installed plugin to the marketplace's latest.
-function updatePluginIn(rt) {
-    const cmd = rt.name === 'claude'
-        ? ['claude', 'plugin', 'update', 'vitrinka@lovinka']
-        : ['codex', 'plugin', 'marketplace', 'upgrade'];
-    return spawnSync(cmd[0], cmd.slice(1), { stdio: 'inherit' }).status === 0;
-}
+// The plugin REFRESH command per runtime lives in updateCmd, which runs it
+// through the tui task plumbing (async + captured output) rather than a bare
+// inherited spawnSync.
 // ---------- setup state probing (shared by install / doctor / uninstall) ----------
 const SHIM_CONTENT = `#!/bin/sh\nexec node "${CLI_PATH}" "$@"\n`;
 function shimPathOf(home) { return join(home, '.local', 'bin', 'vitrinka'); }
@@ -1835,6 +1913,13 @@ async function installCmd(args) {
     row(tokenSrc !== 'missing', 'token', tokenSrc === 'missing' ? 'missing — writes will 401' : `present (${tokenSrc === 'env' ? '$VITRINKA_TOKEN' : tokenPath()})`);
     row(!!op, 'operator', op || 'unset — board writes stay anonymous');
     row(uiOk, 'claude ui', uiOk ? 'footer badge wired' : 'not wired');
+    // The journey-recorder extension is offered, not assumed — and only where a
+    // Chromium browser actually exists to load it into.
+    const extFound = extBrowsers().filter((b) => extBrowserFound(b) !== false).map((b) => b.name);
+    const extHave = extInstalledVersion(extDefaultDir());
+    row(!!extHave, 'extension', extHave ? `recorder ${extHave} (${extDefaultDir()})`
+        : extFound.length ? `will offer — found ${extFound.join(', ')}`
+            : 'no Chromium browser found');
     console.log('');
     // ---- silent steps: plugins, shim, PATH, completion (reversible, own dirs) ----
     for (const rt of runtimes) {
@@ -1935,6 +2020,34 @@ async function installCmd(args) {
     else {
         console.log('claude ui: skipped (re-run any time: vitrinka install-claude)');
     }
+    // 5. Journey-recorder extension. This is also the backfill path: a machine
+    // that ran `install` before the extension existed gets offered it on the next
+    // run, and an already-installed one has its update host re-registered so a
+    // browser added since (or a CLI that moved) starts working again.
+    if (args['no-extension'] === true) {
+        console.log('extension: skipped (--no-extension)');
+    }
+    else if (extHave) {
+        const reg = extRegisterOutcome(registerExtHost().wrote);
+        if (reg.ok)
+            console.log(`✓ extension ${extHave} — update host registered for ${reg.who}`);
+        else
+            console.error(`⚠ extension ${extHave} — update host registered for ${reg.who} (see errors above); in-place updates will not work: vitrinka extension doctor`);
+    }
+    else if (!extFound.length && args.extension !== true) {
+        console.log('extension: skipped (no Chromium browser found — install one, then: vitrinka extension setup)');
+    }
+    else if (args.extension === true
+        || (!noPrompt && promptYesNo(`Install the journey-recorder extension for ${extFound.join(' / ')}? [Y/n] `))) {
+        // soft: an unreachable shelf reports itself and setup continues.
+        await extensionSetupCmd({}, true);
+    }
+    else if (noPrompt) {
+        console.log('extension: skipped (non-interactive — run `vitrinka extension setup`, or pass --extension)');
+    }
+    else {
+        console.log('extension: skipped (re-run any time: vitrinka extension setup)');
+    }
     // ---- environment checks (non-fatal) ----
     if (spawnSync('cwebp', ['-version'], { stdio: 'ignore' }).error) {
         console.error('⚠ cwebp missing (brew install webp) — snap falls back to PNG');
@@ -2783,89 +2896,216 @@ function pkgVersion() {
         return ''; // no package.json next to the CLI (odd layout) — version is cosmetic here
     }
 }
-// updateCmd updates the CLI source (git pull in a repo checkout, `npm i -g` for
-// a global npm install — detected from where the running file lives), then
-// refreshes every surface a previous install put on this machine: the skills
-// bundle (+ /vitrinka:listen command stub) and, ONLY where it was consented to
-// before, the Claude Code UI wiring. It never asks new consent questions —
-// that stays `vitrinka install`'s job. The refresh steps re-exec the (possibly
-// just replaced) CLI file so they run the NEW code, not this stale process.
-async function updateCmd(_args) {
+// installKind — the human name for how the running CLI got onto this machine.
+// It decides BOTH what `update` does (git pull vs package-manager install) and
+// which package manager owns the global copy: an `npm i -g` from a
+// bun/pnpm-installed CLI updates a SHADOWED prefix and the running copy stays
+// stale forever (repeat-update loop, 2026-07-18).
+export function installKind(cliPath, isRepo) {
+    if (isRepo)
+        return 'repo';
+    if (cliPath.includes('/.bun/'))
+        return 'bun';
+    if (cliPath.includes('/pnpm/'))
+        return 'pnpm';
+    return 'npm';
+}
+// clip — one terminal row's worth of a line, ellipsised. Spinner titles must
+// never wrap: a wrapped title leaves orphaned rows behind on every repaint.
+function clip(s, width) {
+    return s.length > width ? `${s.slice(0, width - 1)}…` : s;
+}
+// lastLine — the newest meaningful line of a child's output, sanitized (child
+// tools emit their own spinners and colors) and clipped to fit beside ours.
+export function lastLine(buf, width = 56) {
+    const lines = buf.split(/\r?\n|\r/).map(stripControl).filter(Boolean);
+    return clip(lines[lines.length - 1] || '', width);
+}
+// runStep — spawn a child under a running tui task, retitling the task with the
+// child's newest output line so the user sees WHAT the tool is doing rather
+// than just that something is. Two rules make this the only way `update` runs
+// a subprocess:
+//   * ASYNC, never spawnSync — a synchronous child blocks the event loop, which
+//     freezes the spinner's clock and reproduces the exact "terminal is stuck"
+//     symptom we are removing.
+//   * CAPTURED, not inherited — a child writing to the same TTY scribbles over
+//     the spinner. The transcript is replayed only where it earns its space: on
+//     failure (there it IS the diagnosis) and in --verbose (no spinner to protect).
+function runStep(t, label, bin, argv, plain) {
+    return new Promise((res) => {
+        let out = '';
+        let stdout = '';
+        const child = spawn(bin, argv, { stdio: ['ignore', 'pipe', 'pipe'] });
+        const feed = (isOut) => (b) => {
+            const s = b.toString();
+            out += s;
+            if (isOut)
+                stdout += s;
+            if (plain)
+                (isOut ? process.stdout : process.stderr).write(s);
+            else {
+                // Budget the child's line against the REAL terminal width: clack's
+                // gutter + our label + the `[12s]` timer all share the row, and a
+                // title that wraps leaves an orphan row behind on every repaint.
+                const room = (process.stdout.columns || 80) - label.length - 14;
+                const l = room > 12 ? lastLine(out, room) : '';
+                if (l)
+                    t.message(`${label} ${tui.pc.dim(`· ${l}`)}`);
+            }
+        };
+        child.stdout.on('data', feed(true));
+        child.stderr.on('data', feed(false));
+        child.on('error', (e) => res({ ok: false, out: `${out}${e.message}\n`, stdout }));
+        child.on('close', (code) => res({ ok: code === 0, out, stdout }));
+    });
+}
+// pluginOutcome — condense a plugin manager's chatter into ONE result phrase.
+// Claude prints `✔ Plugin "vitrinka" updated from <sha> to <sha> for scope
+// user. Restart to apply changes.`; codex words it differently. Unrecognized
+// (or future) formats fall back to the last meaningful line, so the step still
+// reports something TRUE instead of a generic "done".
+export function pluginOutcome(out) {
+    const upd = /updated from ([0-9a-f]{7,40}) to ([0-9a-f]{7,40})/i.exec(out);
+    if (upd)
+        return `updated ${upd[1].slice(0, 7)} → ${upd[2].slice(0, 7)}`;
+    const at = /already at the latest version \(([0-9a-f]{7,40})\)/i.exec(out);
+    if (at)
+        return `already at ${at[1].slice(0, 7)}`;
+    if (/already (?:at the latest|up[\s-]?to[\s-]?date)|no updates? available|nothing to update/i.test(out)) {
+        return 'already up to date';
+    }
+    // The task line already carries our own ✓ — drop the child's result glyph so
+    // the fallback doesn't render a stuttering "✓ ✔ …".
+    return lastLine(out, 64).replace(/^[✔✓✗✖•*-]\s*/, '') || 'refreshed';
+}
+// updateCmd updates the CLI source (git pull in a repo checkout, a global
+// install through the owning package manager otherwise — detected from where
+// the running file lives), then refreshes every surface a previous install put
+// on this machine: the plugins in each agent runtime and, ONLY where it was
+// consented to before, the Claude Code UI wiring. It never asks new consent
+// questions — that stays `vitrinka install`'s job. The refresh steps re-exec
+// the (possibly just replaced) CLI file so they run the NEW code, not this
+// stale process.
+//
+// Every step runs inside a tui task with a live elapsed timer, because the slow
+// legs here (registry read, global install, `claude plugin update` at ~10s) are
+// silent third-party subprocesses — without the ticking clock and their piped
+// output the terminal reads as hung. `--verbose` drops the spinners and hands
+// the terminal to the children instead.
+async function updateCmd(args) {
+    const plain = args.verbose === true;
+    const task = (title) => tui.task(title, plain);
     const repoTop = git(['rev-parse', '--show-toplevel'], dirname(CLI_PATH));
+    const kind = installKind(CLI_PATH, !!repoTop);
+    const current = pkgVersion();
+    tui.intro(`vitrinka update · ${current || '?'} · ${kind === 'repo' ? 'repo checkout' : `${kind} global install`}`);
+    let moved = ''; // what the version leg actually changed (drives the outro)
+    let news = ''; // changelog / commit log, shown once the CLI is current
     if (repoTop) {
         // Repo checkout — the shim/MCP run the source directly, so a pull IS the update.
-        const before = git(['rev-parse', '--short', 'HEAD'], repoTop);
-        console.log(`repo checkout ${repoTop} (${before || '?'}) — git pull --ff-only…`);
-        const pull = spawnSync('git', ['-C', repoTop, 'pull', '--ff-only'], { stdio: 'inherit' });
-        if (pull.status !== 0)
-            fail('update: git pull --ff-only failed — fix the repo state (dirty tree / diverged branch) and re-run');
-        const after = git(['rev-parse', '--short', 'HEAD'], repoTop);
-        if (after === before)
-            console.log(`✓ already up to date (${after})`);
+        const before = git(['rev-parse', '--short', 'HEAD'], repoTop) || '?';
+        const t = task(`pulling ${clip(repoTop, 48)}`);
+        const pull = await runStep(t, 'git pull --ff-only', 'git', ['-C', repoTop, 'pull', '--ff-only'], plain);
+        if (!pull.ok) {
+            t.fail(`source ✗ git pull --ff-only failed in ${clip(repoTop, 48)}`);
+            if (pull.out.trim())
+                tui.note(pull.out.trim().slice(-1200), 'git says');
+            tui.outro('update aborted — fix the repo state (dirty tree / diverged branch) and re-run');
+            process.exit(1);
+        }
+        const after = git(['rev-parse', '--short', 'HEAD'], repoTop) || '?';
+        if (after === before) {
+            t.done(`source ✓ already up to date (${after})`);
+        }
         else {
-            console.log(`✓ updated ${before} → ${after}`);
+            t.done(`source ✓ ${before} → ${after}`);
+            moved = `${before} → ${after}`;
             // What's new — the pulled commits, capped so a long-idle machine doesn't scroll.
             const log = git(['log', '--oneline', '--no-decorate', `${before}..${after}`], repoTop);
             if (log) {
                 const lines = log.split('\n');
-                for (const l of lines.slice(0, 30))
-                    console.log(`  ${l}`);
-                if (lines.length > 30)
-                    console.log(`  … ${lines.length - 30} more`);
+                news = lines.slice(0, 30).join('\n') + (lines.length > 30 ? `\n… ${lines.length - 30} more` : '');
             }
         }
     }
     else {
-        // Global npm install — compare against the registry, update when behind.
-        const current = pkgVersion();
-        const view = spawnSync('npm', ['view', '@lovinka/vitrinka', 'version'], { encoding: 'utf8' });
-        const latest = view.status === 0 ? view.stdout.trim() : '';
+        // Global install — compare against the registry, install when behind.
+        const t = task('checking the registry for a newer release');
+        const view = await runStep(t, 'npm view', 'npm', ['view', '@lovinka/vitrinka', 'version'], plain);
+        const latest = view.ok ? view.stdout.trim() : '';
         if (!latest) {
-            fail(`update: could not read the registry version (npm view @lovinka/vitrinka version): ${String(view.stderr || view.error || '').trim().slice(0, 200) || 'unknown error'}`);
+            t.fail('registry ✗ could not read the latest version');
+            if (view.out.trim())
+                tui.note(view.out.trim().slice(-800), 'npm view @lovinka/vitrinka version');
+            tui.outro('update aborted — the npm registry was unreachable; check the network and re-run');
+            process.exit(1);
         }
         if (latest === current) {
-            console.log(`✓ already at the latest version (${current})`);
+            t.done(`registry ✓ ${current} is the latest release`);
         }
         else {
-            // Update through the package manager that OWNS the running copy — an
-            // `npm i -g` from a bun/pnpm-installed CLI updates a SHADOWED prefix and
-            // the running copy stays stale forever (repeat-update loop, 2026-07-18).
-            const mgr = CLI_PATH.includes('/.bun/')
-                ? ['bun', ['add', '-g', '@lovinka/vitrinka@latest']]
-                : CLI_PATH.includes('/pnpm/')
-                    ? ['pnpm', ['add', '-g', '@lovinka/vitrinka@latest']]
-                    : ['npm', ['install', '-g', '@lovinka/vitrinka@latest']];
-            console.log(`updating @lovinka/vitrinka ${current || '?'} → ${latest} (${mgr[0]})…`);
-            const inst = spawnSync(mgr[0], mgr[1], { stdio: 'inherit' });
-            if (inst.status !== 0)
-                fail(`update: ${mgr[0]} ${mgr[1].join(' ')} failed (see output above)`);
+            t.done(`registry ✓ ${current || '?'} → ${latest} available`);
+            const argvOf = {
+                bun: ['add', '-g', '@lovinka/vitrinka@latest'],
+                pnpm: ['add', '-g', '@lovinka/vitrinka@latest'],
+                npm: ['install', '-g', '@lovinka/vitrinka@latest'],
+            };
+            const mgr = kind === 'repo' ? 'npm' : kind;
+            const t2 = task(`installing ${latest} with ${mgr}`);
+            const inst = await runStep(t2, mgr, mgr, argvOf[mgr], plain);
+            if (!inst.ok) {
+                t2.fail(`cli ✗ ${mgr} ${argvOf[mgr].join(' ')} failed`);
+                if (inst.out.trim())
+                    tui.note(inst.out.trim().slice(-1200), `${mgr} says`);
+                tui.outro('update aborted — the install failed; nothing else was touched');
+                process.exit(1);
+            }
             // Verify the RUNNING copy actually changed on disk — if not, another
             // install is shadowing it on PATH; say so instead of claiming success.
             const after = pkgVersion();
             if (after === current) {
-                console.error(`⚠ installed ${latest}, but the copy at ${CLI_PATH} is still ${current || '?'} — another install shadows it on PATH. Inspect: which -a vitrinka`);
+                t2.fail(`cli ⚠ installed ${latest}, but ${CLI_PATH} is still ${current || '?'}`);
+                tui.warn('another install shadows it on PATH — inspect: which -a vitrinka');
             }
             else {
-                console.log(`✓ @lovinka/vitrinka ${after || latest}`);
+                t2.done(`cli ✓ @lovinka/vitrinka ${after || latest}`);
+                moved = `${current || '?'} → ${after || latest}`;
             }
-            // What's new — the package files were replaced in place, so the
-            // CHANGELOG next to the CLI is the NEW one; print its sections > current.
+            // The package files were replaced in place, so the CHANGELOG next to the
+            // CLI is the NEW one; show its sections newer than the version we had.
             try {
-                const news = changelogSince(readFileSync(join(dirname(CLI_PATH), '..', 'CHANGELOG.md'), 'utf8'), current);
-                if (news)
-                    console.log(`\n${news}\n`);
+                news = changelogSince(readFileSync(join(dirname(CLI_PATH), '..', 'CHANGELOG.md'), 'utf8'), current);
             }
             catch {
                 // Older packages ship no CHANGELOG.md — nothing to show.
             }
         }
     }
-    // Refresh installed surfaces from the NEW code — plugins where installed,
-    // Claude wiring only where the footer badge shows prior consent.
-    const rerun = (sub) => spawnSync(process.execPath, [CLI_PATH, ...sub], { stdio: 'inherit' }).status === 0;
-    for (const rt of pluginRuntimes()) {
-        if (rt.installed && !updatePluginIn(rt)) {
-            console.error(`⚠ update: ${rt.name} plugin refresh failed — re-run its plugin update manually`);
+    if (news)
+        tui.note(news, "what's new");
+    // ---- installed surfaces: plugins where installed, Claude wiring only where
+    // the footer badge shows prior consent. Refreshed from the NEW code. ----
+    const probe = task('checking installed surfaces');
+    const runtimes = pluginRuntimes();
+    probe.done(`surfaces ✓ ${runtimes.map((r) => `${r.name} ${r.installed ? 'plugin' : r.present ? '(no plugin)' : '(absent)'}`).join(' · ')}`);
+    const problems = [];
+    let restartHint = false;
+    for (const rt of runtimes.filter((r) => r.installed)) {
+        const cmd = rt.name === 'claude'
+            ? ['claude', 'plugin', 'update', 'vitrinka@lovinka']
+            : ['codex', 'plugin', 'marketplace', 'upgrade'];
+        const t = task(`refreshing the ${rt.name} plugin (skills + commands)`);
+        const r = await runStep(t, `${rt.name} plugin`, cmd[0], cmd.slice(1), plain);
+        if (!r.ok) {
+            t.fail(`${rt.name} plugin ✗ refresh failed`);
+            if (r.out.trim())
+                tui.note(r.out.trim().slice(-800), `${rt.name} says`);
+            problems.push(`${rt.name} plugin — re-run: ${cmd.join(' ')}`);
+        }
+        else {
+            t.done(`${rt.name} plugin ✓ ${pluginOutcome(r.out)}`);
+            if (/restart/i.test(r.out))
+                restartHint = true;
         }
     }
     // Remove the retired statusline extension from existing installs, then refresh
@@ -2880,10 +3120,691 @@ async function updateCmd(_args) {
         }
         catch { /* malformed settings.json — treat as not-wired; install-claude reports it */ }
     }
-    if (consented && !rerun(['install-claude'])) {
-        console.error('⚠ update: Claude UI refresh failed — re-run: vitrinka install-claude');
+    if (consented) {
+        const t = task('refreshing the Claude Code UI wiring');
+        const r = await runStep(t, 'install-claude', process.execPath, [CLI_PATH, 'install-claude'], plain);
+        if (r.ok) {
+            t.done('claude ui ✓ board footer badges current');
+        }
+        else {
+            t.fail('claude ui ✗ refresh failed');
+            if (r.out.trim())
+                tui.note(r.out.trim().slice(-800), 'install-claude says');
+            problems.push('claude ui — re-run: vitrinka install-claude');
+        }
+    }
+    // The recorder extension is a surface too: it self-updates hourly through the
+    // native host, but a CLI update is a good moment to catch a machine whose
+    // browser has been closed for a week. Silent when it isn't installed.
+    const extHave = extInstalledVersion(extDefaultDir());
+    if (extHave) {
+        const t = task(`checking the recorder extension (${extHave})`);
+        try {
+            const rel = await extLatestRelease();
+            const moved = compareVersions(rel.version, extHave) > 0;
+            if (moved)
+                await extInstallLocked(rel, extDefaultDir());
+            const reg = extRegisterOutcome(registerExtHost().wrote);
+            const where = moved ? `${extHave} → ${rel.version} (reloads itself within the hour)` : `${extHave} is current`;
+            if (reg.ok) {
+                t.done(`extension ✓ ${where}`);
+            }
+            else {
+                // Registering nothing is not "current" — say so instead of a ✓ over a
+                // host chain that cannot answer the popup.
+                t.fail(`extension ⚠ ${where}, but the update host is registered for ${reg.who}`);
+                problems.push('extension — no update host registered: vitrinka extension doctor --fix');
+            }
+        }
+        catch (e) {
+            // Never fail a CLI update over the extension — it keeps recording either
+            // way, and the popup can install the release itself later.
+            t.fail(`extension ⚠ ${String(e.message || e)}`);
+            problems.push('extension — re-run: vitrinka extension update');
+        }
+    }
+    if (problems.length) {
+        tui.warn(`${problems.length} step(s) need a hand:\n${problems.map((p) => `  · ${p}`).join('\n')}`);
+    }
+    const tail = restartHint ? ' · restart Claude Code sessions to load it' : '';
+    tui.outro(moved
+        ? `updated ${moved}${tail} — try: vitrinka --help`
+        : `already up to date${tail} — try: vitrinka --help`);
+}
+// ---------- extension: the journey-recorder browser extension ----------
+//
+// The recorder ships UNPACKED (mesh-only tool, no Web Store), and Chrome never
+// auto-updates an unpacked extension. What Chrome DOES do is re-read the whole
+// folder from disk on `chrome.runtime.reload()` — so an update is really "swap
+// the files, then reload". An extension cannot write its own folder, so this
+// CLI is the writer and Chrome reaches it over a native-messaging host:
+//
+//   setup   unpack the marketplace zip into the canonical dir + register the host
+//   update  swap the dir to the newest release (the extension reloads itself)
+//   doctor  report every link in that chain; --fix re-registers what it can
+//   host    the stdio protocol Chrome speaks (hidden — Chrome spawns it)
+//
+// The extension's id is pinned by a fixed `key` in its manifest because
+// allowed_origins has to name ONE id, and an unpacked extension's id is
+// otherwise a hash of wherever the folder happens to live.
+const EXT_ID = 'lidjccailicbgjdfaplpgmbmmecehlfo';
+const EXT_HOST_NAME = 'in.vitrinka.updater';
+const EXT_APP = 'vitrinka-recorder';
+const EXT_MARKET_DEFAULT = 'https://apps.fixit.app';
+// $VITRINKA_EXT_MARKET repoints the release feed — the seam the tests use, and
+// what a self-hosted pultik shelf would set.
+function extMarket() {
+    return (process.env.VITRINKA_EXT_MARKET || EXT_MARKET_DEFAULT).replace(/\/+$/, '');
+}
+// A native-messaging frame is capped at 1 MB by Chrome in both directions; ours
+// are tiny, so anything near the cap is a desync, not a big message.
+const EXT_FRAME_MAX = 1024 * 1024;
+function extConfigHome() { return join(process.env.HOME || '', '.config', 'vitrinka'); }
+// ONE canonical folder, deliberately not overridable: the host Chrome spawns
+// gets no arguments, so a per-user location would have to be persisted and kept
+// in sync, and every "update" from the popup could then target the wrong copy.
+// $HOME is the only seam (which is also how the tests isolate).
+function extDefaultDir() { return join(extConfigHome(), 'extension'); }
+function extShimPath() { return join(extConfigHome(), 'extension-host.sh'); }
+// compareVersions — dotted numeric compare, exported for the popup-parity test.
+// Returns >0 when a outranks b. Non-numeric junk sorts as 0 rather than NaN, so
+// a malformed feed can never claim to be newer.
+export function compareVersions(a, b) {
+    const pa = String(a).split('.'), pb = String(b).split('.');
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const na = Number(pa[i]) || 0, nb = Number(pb[i]) || 0;
+        if (na !== nb)
+            return na - nb;
+    }
+    return 0;
+}
+export function extBrowsers(platform = process.platform, home = process.env.HOME || '') {
+    const mac = [
+        ['chrome', 'Google/Chrome', 'Google Chrome.app'],
+        ['brave', 'BraveSoftware/Brave-Browser', 'Brave Browser.app'],
+        ['edge', 'Microsoft Edge', 'Microsoft Edge.app'],
+        ['chromium', 'Chromium', 'Chromium.app'],
+    ];
+    const linux = [
+        ['chrome', 'google-chrome', ['google-chrome', 'google-chrome-stable']],
+        ['brave', 'BraveSoftware/Brave-Browser', ['brave-browser', 'brave']],
+        ['edge', 'microsoft-edge', ['microsoft-edge', 'microsoft-edge-stable']],
+        ['chromium', 'chromium', ['chromium', 'chromium-browser']],
+    ];
+    if (platform === 'darwin') {
+        return mac.map(([name, rel, app]) => {
+            const profile = join(home, 'Library', 'Application Support', ...rel.split('/'));
+            return {
+                name, profile, bins: [],
+                dir: join(profile, 'NativeMessagingHosts'),
+                // Per-user installs land in ~/Applications, not /Applications.
+                apps: [join('/Applications', app), join(home, 'Applications', app)],
+            };
+        });
+    }
+    return linux.map(([name, rel, bins]) => {
+        const profile = join(home, '.config', ...rel.split('/'));
+        return { name, profile, bins, apps: [], dir: join(profile, 'NativeMessagingHosts') };
+    });
+}
+// An executable of that name on PATH — `delimiter` because the separator is
+// platform-specific, and the mode bit because a plain file (or a directory)
+// called `google-chrome` is not a browser.
+function onPath(bin) {
+    return (process.env.PATH || '').split(delimiter).some((d) => {
+        if (!d)
+            return false;
+        const p = join(d, bin);
+        try {
+            const st = statSync(p);
+            return st.isFile() && (st.mode & 0o111) !== 0;
+        }
+        catch {
+            return false; // not there (ENOENT) — the ordinary case for most PATH dirs
+        }
+    });
+}
+export function extBrowserFound(b) {
+    if (b.apps.some((p) => existsSync(p)))
+        return 'app';
+    if (b.bins.some(onPath))
+        return 'path';
+    return existsSync(join(b.profile, 'Local State')) ? 'profile' : false;
+}
+// extBrowserInstalled — the strong reading, for anything that ASSERTS the
+// browser exists (doctor's "installed, host NOT registered" alarm).
+export function extBrowserInstalled(b) {
+    const e = extBrowserFound(b);
+    return e === 'app' || e === 'path';
+}
+export function extHostManifest(shim) {
+    return JSON.stringify({
+        name: EXT_HOST_NAME,
+        description: 'Vitrinka journey-recorder updater',
+        path: shim,
+        type: 'stdio',
+        allowed_origins: [`chrome-extension://${EXT_ID}/`],
+    }, null, 2) + '\n';
+}
+// extShim — Chrome execs this file, so it must be executable and speak the
+// framed protocol on stdout and NOTHING else. node + the CLI path are baked in
+// at setup time; `extension doctor` catches a stale pair after a reinstall.
+export function extShim(nodeBin, cliPath) {
+    return [
+        '#!/bin/sh',
+        '# vitrinka native-messaging host — generated by `vitrinka extension setup`.',
+        '# Chrome speaks a 4-byte-length + JSON protocol on stdin/stdout; anything',
+        '# else printed to stdout corrupts the stream, so keep this a bare exec.',
+        `exec ${JSON.stringify(nodeBin)} ${JSON.stringify(cliPath)} extension host`,
+        '',
+    ].join('\n');
+}
+// extTargetBrowsers — who gets a host manifest: the browsers we found any
+// evidence for (including a leftover profile — a spare manifest is harmless and
+// the browser may come back). A machine where we detect NONE (a fresh box, or a
+// Chromium fork we don't know) falls back to all of them, so setup still leaves
+// something that works. `browsers` is injectable so both branches are testable
+// without depending on what happens to be installed on the test machine.
+export function extTargetBrowsers(browsers = extBrowsers()) {
+    const found = browsers.filter((b) => extBrowserFound(b) !== false);
+    return { targets: found.length ? found : browsers, found, all: found.length === 0 };
+}
+// extRegisterOutcome — how `install` and `update` report a re-registration.
+// Shared so the "wrote nothing" case is ONE branch with one test rather than
+// two hand-written checks: an empty list is exactly the broken host that
+// re-registration exists to repair, so it must never read as success.
+export function extRegisterOutcome(wrote) {
+    return wrote.length
+        ? { ok: true, who: wrote.join(' · ') }
+        : { ok: false, who: 'NO browser' };
+}
+export function extHostVerdict(name, evidence, manifest) {
+    const installed = evidence === 'app' || evidence === 'path';
+    if (manifest === 'stale')
+        return { level: 'bad', text: `${name}: host manifest is stale` };
+    if (manifest === 'missing') {
+        if (installed)
+            return { level: 'bad', text: `${name}: installed, host NOT registered` };
+        if (evidence === 'profile')
+            return { level: 'note', text: `${name}: profile present but the browser looks uninstalled — not registered` };
+        return { level: 'note', text: `${name}: not installed` };
+    }
+    const note = installed ? ''
+        : evidence === 'profile' ? ' (profile only — browser looks uninstalled)'
+            : ' (browser not installed — harmless)';
+    return { level: 'ok', text: `${name}: host registered${note}` };
+}
+// registerExtHost writes the shim + one manifest per target browser.
+function registerExtHost(targets) {
+    const shim = extShimPath();
+    mkdirSync(dirname(shim), { recursive: true });
+    writeFileSync(shim, extShim(process.execPath, CLI_PATH));
+    chmodSync(shim, 0o755);
+    const body = extHostManifest(shim);
+    const wrote = [];
+    for (const { name, dir } of targets ?? extTargetBrowsers().targets) {
+        try {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(join(dir, `${EXT_HOST_NAME}.json`), body);
+            wrote.push(name);
+        }
+        catch (e) {
+            // A browser we can't write to (locked-down profile) must not sink setup —
+            // the others still work, and doctor reports the gap.
+            console.error(`vitrinka: could not register the host for ${name}: ${String(e.message || e)}`);
+        }
     }
-    console.log('update done — try: vitrinka --help');
+    return { shim, wrote };
+}
+function extInstalledVersion(dir) {
+    try {
+        return String(JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8')).version || '');
+    }
+    catch {
+        return ''; // not installed (or mid-swap) — callers treat '' as "absent"
+    }
+}
+const EXT_SHA256_RE = /^[0-9a-f]{64}$/;
+// Hard ceiling on a release artifact, independent of what the feed claims. The
+// real one is ~64 KB; this is headroom, not a target.
+const EXT_ZIP_MAX = 32 * 1024 * 1024;
+async function extLatestRelease() {
+    const url = `${extMarket()}/api/releases/${EXT_APP}/latest`;
+    const r = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+    if (!r.ok)
+        throw new Error(`${url} → HTTP ${r.status}`);
+    const j = await r.json();
+    if (!j.version || !j.artifact)
+        throw new Error(`${url} returned no version/artifact`);
+    const sha256 = String(j.sha256 ?? '').trim().toLowerCase();
+    if (!EXT_SHA256_RE.test(sha256)) {
+        throw new Error(`${url} has no usable sha256 (${JSON.stringify(j.sha256 ?? null)}) — refusing an unverifiable release`);
+    }
+    return { version: j.version, artifact: j.artifact, sha256, size: j.size };
+}
+// extDownload buffers a release under a hard byte cap. The cap matters because
+// the caller holds the whole artifact in memory to hash it: without one, a
+// shelf lying about its size (or anything that can answer for extMarket()) can
+// make every popup update balloon the host until it dies. The advertised size
+// is the expectation when present; EXT_ZIP_MAX is the backstop when it is not.
+async function extDownload(url, advertised) {
+    const res = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+    if (!res.ok)
+        throw new Error(`${url} → HTTP ${res.status}`);
+    const cap = advertised > 0 ? Math.min(advertised, EXT_ZIP_MAX) : EXT_ZIP_MAX;
+    // EVERY rejection past this point goes through here: an unconsumed undici body
+    // keeps its connection (and the server's ability to keep streaming) alive, so
+    // "throw immediately" without a cancel is not actually immediate.
+    const reject = async (msg) => {
+        await res.body?.cancel().catch(() => { });
+        throw new Error(msg);
+    };
+    const declared = Number(res.headers.get('content-length') || 0);
+    if (declared > cap) {
+        return reject(`${url} declares ${declared} bytes — too large, the feed advertised size ${cap}`);
+    }
+    if (!res.body)
+        throw new Error(`${url} returned no body`);
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of res.body) {
+        total += chunk.length;
+        if (total > cap) {
+            // Stop reading rather than finish and check afterwards — the point is to
+            // never hold the oversized body at all.
+            return reject(`${url} is too large — exceeded ${cap} bytes (advertised size ${advertised || 'none'})`);
+        }
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks, total);
+}
+// extInstallRelease downloads a release and swaps it into `dir`.
+//
+// Everything stages inside dir's PARENT so each rename stays on one filesystem
+// (a tmpdir on another volume would make renameSync throw EXDEV). The previous
+// generation is cleared at the START of the next update, never at the end of
+// this one: between the swap and the extension's reload, a running extension
+// still resolves its files through the old inode.
+async function extInstallRelease(rel, dir) {
+    const stage = `${dir}.stage`;
+    const prev = `${dir}.old`;
+    rmSync(stage, { recursive: true, force: true });
+    rmSync(prev, { recursive: true, force: true });
+    mkdirSync(stage, { recursive: true });
+    const url = `${extMarket()}/releases/${EXT_APP}/${rel.version}/${rel.artifact}`;
+    let zipBytes;
+    try {
+        zipBytes = await extDownload(url, Number(rel.size) || 0);
+    }
+    catch (e) {
+        rmSync(stage, { recursive: true, force: true });
+        throw e;
+    }
+    // Unconditional: extLatestRelease already refused a release without a usable
+    // digest, so there is no "no checksum to check" branch left to fall through.
+    const got = createHash('sha256').update(zipBytes).digest('hex');
+    if (got !== rel.sha256) {
+        rmSync(stage, { recursive: true, force: true });
+        throw new Error(`checksum mismatch for ${rel.artifact} (feed ${rel.sha256.slice(0, 12)}…, got ${got.slice(0, 12)}…) — refusing to install`);
+    }
+    const zipPath = join(stage, 'release.zip');
+    writeFileSync(zipPath, zipBytes);
+    const unzip = spawnSync('unzip', ['-q', '-o', zipPath, '-d', stage], { encoding: 'utf8' });
+    if (unzip.error || unzip.status !== 0) {
+        rmSync(stage, { recursive: true, force: true });
+        throw new Error(`unzip failed (${unzip.error ? unzip.error.message : `exit ${unzip.status}`}${(unzip.stderr || '').trim() ? `: ${unzip.stderr.trim()}` : ''}) — install unzip and re-run`);
+    }
+    rmSync(zipPath, { force: true });
+    // The zip unpacks to a single vitrinka-recorder/ folder; tolerate a flat one.
+    let root = stage;
+    if (!existsSync(join(root, 'manifest.json'))) {
+        const subs = readdirSync(stage, { withFileTypes: true })
+            .filter((d) => d.isDirectory() && existsSync(join(stage, d.name, 'manifest.json')));
+        if (subs.length !== 1) {
+            rmSync(stage, { recursive: true, force: true });
+            throw new Error(`${rel.artifact} has no single folder containing manifest.json — bad release artifact`);
+        }
+        root = join(stage, subs[0].name);
+    }
+    mkdirSync(dirname(dir), { recursive: true });
+    if (existsSync(dir))
+        renameSync(dir, prev);
+    renameSync(root, dir);
+    rmSync(stage, { recursive: true, force: true });
+}
+// extInstallLocked — one updater at a time, then install. Two Chrome ports mean
+// two host processes, and two concurrent swaps of the same dir corrupt it.
+// mkdir is the atomic primitive; a lock older than the download timeout is
+// treated as abandoned by whatever died holding it.
+async function extInstallLocked(rel, dir) {
+    const lock = `${dir}.lock`;
+    try {
+        const age = Date.now() - statSync(lock).mtimeMs;
+        if (age > 150_000)
+            rmSync(lock, { recursive: true, force: true });
+    }
+    catch { /* nothing holds it (ENOENT) — the mkdir below claims it */ }
+    mkdirSync(dirname(lock), { recursive: true });
+    try {
+        mkdirSync(lock, { recursive: false });
+    }
+    catch (e) {
+        // EEXIST is the lock doing its job. Anything else (EACCES, ENOSPC) is a
+        // real fault and must not be reported as "someone else is installing".
+        if (e.code !== 'EEXIST')
+            throw e;
+        throw new Error(`another vitrinka updater holds ${lock} — retry in a moment, or remove it if nothing is running`);
+    }
+    try {
+        await extInstallRelease(rel, dir);
+    }
+    finally {
+        rmSync(lock, { recursive: true, force: true });
+    }
+}
+async function extensionCmd(argv, args) {
+    const sub = argv[0] && !argv[0].startsWith('--') ? argv[0] : '';
+    if (sub === 'setup')
+        return extensionSetupCmd(args);
+    if (sub === 'update')
+        return extensionUpdateCmd(args);
+    if (sub === 'doctor')
+        return extensionDoctorCmd(args);
+    if (sub === 'host')
+        return extensionHostCmd();
+    console.error(sub
+        ? `extension: unknown subcommand ${JSON.stringify(sub)}`
+        : 'extension: needs a subcommand');
+    console.error('\n' + renderCmdHelp('extension'));
+    process.exit(2);
+}
+// soft: called from `vitrinka install` as an optional extra, where a shelf
+// outage must report itself and let machine setup finish rather than exit(1)
+// out of the middle of someone's onboarding.
+async function extensionSetupCmd(args, soft = false) {
+    const plain = args.verbose === true;
+    const task = (title) => tui.task(title, plain);
+    const dir = extDefaultDir();
+    const have = extInstalledVersion(dir);
+    tui.intro(`vitrinka extension setup · ${clip(dir, 52)}`);
+    const t = task('checking the marketplace for the current release');
+    let rel;
+    try {
+        rel = await extLatestRelease();
+        t.done(`release ✓ ${EXT_APP} ${rel.version}${have ? ` (installed: ${have})` : ''}`);
+    }
+    catch (e) {
+        t.fail(`release ✗ ${String(e.message || e)}`);
+        tui.outro(`extension setup ${soft ? 'skipped' : 'aborted'} — the marketplace was unreachable. On the mesh? ${extMarket()} must resolve.`);
+        if (soft)
+            return;
+        process.exit(1);
+    }
+    if (have === rel.version && args.force !== true) {
+        tui.info(`files ✓ ${dir} already holds ${have} (re-download with --force)`);
+    }
+    else {
+        const t2 = task(`downloading ${rel.artifact}${rel.size ? ` (${Math.round(rel.size / 1024)} KB)` : ''}`);
+        try {
+            await extInstallLocked(rel, dir);
+            t2.done(`files ✓ ${have ? `${have} → ` : ''}${rel.version} unpacked into ${clip(dir, 40)}`);
+        }
+        catch (e) {
+            t2.fail(`files ✗ ${String(e.message || e)}`);
+            tui.outro(`extension setup ${soft ? 'skipped' : 'aborted'} — nothing was swapped in; the previous folder is untouched`);
+            if (soft)
+                return;
+            process.exit(1);
+        }
+    }
+    const t3 = task('looking for browsers to register the update host with');
+    const { targets, all } = extTargetBrowsers();
+    const { wrote } = registerExtHost(targets);
+    if (!wrote.length) {
+        t3.fail('host ✗ could not write a manifest for any browser');
+        tui.outro('extension setup incomplete — see the errors above; it still records, just without in-place updates');
+        if (soft)
+            return;
+        process.exit(1);
+    }
+    const missing = extBrowsers().filter((b) => !wrote.includes(b.name)).map((b) => b.name);
+    t3.done(all
+        ? `host ✓ registered for ${wrote.join(' · ')} — no browser detected, so all of them are covered`
+        : `host ✓ registered for ${wrote.join(' · ')}${missing.length ? ` (${missing.join(', ')} not installed)` : ''}`);
+    if (!all && missing.length) {
+        tui.info(`Install ${missing.length > 1 ? 'one of those' : missing[0]} later? Run \`vitrinka extension doctor --fix\` to register it too.`);
+    }
+    tui.note([
+        `1. open  chrome://extensions  (brave:// · edge:// all work)`,
+        '2. turn on Developer mode, click "Load unpacked"',
+        `3. pick  ${dir}`,
+        '',
+        `The id must read  ${EXT_ID}`,
+        'If you already had the recorder loaded from another folder, REMOVE that',
+        'card — the pinned id makes this a different extension, so the two would',
+        'both answer the shortcuts.',
+    ].join('\n'), 'load it once');
+    const tok = tokenSource();
+    tui.note(tok === 'missing'
+        ? `No token on this machine yet — run \`vitrinka login\`, then use "Fill from the\nvitrinka CLI" on the extension's options page (or just reload the extension).`
+        : `Base URL ${resolveBaseUrl()} and your ${tok === 'env' ? '$VITRINKA_TOKEN' : 'saved'} token are handed to\nthe extension when it first loads — the options page is an override, not a step.`, 'settings');
+    tui.outro(`recorder ${rel.version} ready — future releases install from the popup (or \`vitrinka extension update\`)`);
+}
+async function extensionUpdateCmd(args) {
+    const plain = args.verbose === true;
+    const task = (title) => tui.task(title, plain);
+    const dir = extDefaultDir();
+    const have = extInstalledVersion(dir);
+    if (!have) {
+        console.error(`extension update: nothing installed at ${dir} — run \`vitrinka extension setup\` first`);
+        process.exit(1);
+    }
+    tui.intro(`vitrinka extension update · ${have} · ${clip(dir, 46)}`);
+    const t = task('checking the marketplace');
+    let rel;
+    try {
+        rel = await extLatestRelease();
+    }
+    catch (e) {
+        t.fail(`release ✗ ${String(e.message || e)}`);
+        tui.outro('update aborted — the marketplace was unreachable; nothing was touched');
+        process.exit(1);
+    }
+    const behind = compareVersions(rel.version, have) > 0;
+    t.done(behind ? `release ✓ ${have} → ${rel.version} available` : `release ✓ ${have} is current`);
+    if (!behind && args.force !== true) {
+        tui.outro('already up to date — nothing to do');
+        return;
+    }
+    if (args.check === true) {
+        tui.outro(`update available: ${rel.version} — run \`vitrinka extension update\` to install it`);
+        return;
+    }
+    const t2 = task(`installing ${rel.version}`);
+    try {
+        await extInstallLocked(rel, dir);
+        t2.done(`files ✓ ${have} → ${rel.version}`);
+    }
+    catch (e) {
+        t2.fail(`files ✗ ${String(e.message || e)}`);
+        tui.outro('update aborted — nothing was swapped in; the running extension is untouched');
+        process.exit(1);
+    }
+    tui.outro(`installed ${rel.version} — the extension picks it up within the hour, or instantly from the popup (↻ in chrome://extensions also works)`);
+}
+async function extensionDoctorCmd(args) {
+    const fix = args.fix === true;
+    const dir = extDefaultDir();
+    const lines = [];
+    let bad = 0;
+    const ok = (m) => { lines.push(`  ✓ ${m}`); };
+    const no = (m) => { lines.push(`  ✗ ${m}`); bad++; };
+    tui.intro(`vitrinka extension doctor${fix ? ' --fix' : ''}`);
+    const have = extInstalledVersion(dir);
+    if (have)
+        ok(`files ${have} at ${dir}`);
+    else
+        no(`no manifest.json at ${dir} — run: vitrinka extension setup`);
+    // Registering is idempotent and useful even with no extension unpacked yet,
+    // so --fix is not gated on the folder existing (otherwise "shim missing →
+    // run --fix" would loop on a machine that has lost the folder).
+    if (fix)
+        registerExtHost();
+    const shim = extShimPath();
+    if (!existsSync(shim)) {
+        no(`host shim missing (${shim}) — run: vitrinka extension doctor --fix`);
+    }
+    else {
+        const body = readFileSync(shim, 'utf8');
+        const exec = (statSync(shim).mode & 0o111) !== 0;
+        // The shim bakes in node + the CLI path; a global reinstall can move either.
+        const stale = !body.includes(JSON.stringify(CLI_PATH)) || !body.includes(JSON.stringify(process.execPath));
+        if (!exec)
+            no(`host shim is not executable (${shim}) — run: vitrinka extension doctor --fix`);
+        else if (stale)
+            no(`host shim points at a different node/CLI than this one — run: vitrinka extension doctor --fix`);
+        else
+            ok(`host shim ${shim}`);
+    }
+    // Registration only matters for browsers that exist: a missing manifest for
+    // an uninstalled Edge is not a problem, but a missing one for the browser
+    // you actually use is the whole feature silently not working.
+    const want = extHostManifest(shim);
+    for (const b of extBrowsers()) {
+        const p = join(b.dir, `${EXT_HOST_NAME}.json`);
+        const state = !existsSync(p) ? 'missing' : readFileSync(p, 'utf8') === want ? 'current' : 'stale';
+        const v = extHostVerdict(b.name, extBrowserFound(b), state);
+        const fixHint = ' — run: vitrinka extension doctor --fix';
+        if (v.level === 'ok')
+            ok(v.text);
+        else if (v.level === 'bad')
+            no(`${v.text}${state === 'stale' ? ` (${p})` : ''}${fixHint}`);
+        else
+            lines.push(`  · ${v.text}`);
+    }
+    if (spawnSync('unzip', ['-v'], { stdio: 'ignore' }).error) {
+        no('unzip not found on PATH — in-place updates cannot unpack a release');
+    }
+    else {
+        ok('unzip available');
+    }
+    const tok = tokenSource();
+    if (tok === 'missing')
+        no(`no write token (${tokenPath()}) — run: vitrinka login`);
+    else
+        ok(`token from ${tok === 'env' ? '$VITRINKA_TOKEN' : tokenPath()}`);
+    ok(`base URL ${resolveBaseUrl(strArg(args.base))}`);
+    let latest = '';
+    try {
+        latest = (await extLatestRelease()).version;
+        if (have && compareVersions(latest, have) > 0) {
+            lines.push(`  ↑ ${latest} available — run: vitrinka extension update`);
+        }
+        else if (have) {
+            ok(`marketplace: ${have} is current`);
+        }
+        else {
+            ok(`marketplace: ${latest} is the current release`);
+        }
+    }
+    catch (e) {
+        // Not always "unreachable" any more: a feed that answers without a usable
+        // sha256 is refused here too, and saying "unreachable" would misdirect.
+        no(`marketplace: ${String(e.message || e)}`);
+    }
+    tui.note(lines.join('\n'), `extension · id ${EXT_ID}`);
+    tui.outro(bad
+        ? `${bad} problem(s) — the recorder still records, but in-place updates need the host chain intact`
+        : 'all good — updates install from the popup');
+    if (bad)
+        process.exit(1);
+}
+// extensionHostCmd — the native-messaging endpoint Chrome spawns via the shim.
+//
+// Protocol: 4-byte little-endian length + JSON payload, both directions.
+// stdout IS the wire, so every diagnostic goes to stderr (Chrome logs it).
+//
+// The `config` reply hands the extension this machine's write token. That is
+// not a new exposure: Chrome only lets the allowed_origins extension connect,
+// and any local process could already read ~/.config/vitrinka/token directly.
+async function extensionHostCmd() {
+    const dir = extDefaultDir();
+    const send = (obj) => {
+        const body = Buffer.from(JSON.stringify(obj), 'utf8');
+        const len = Buffer.alloc(4);
+        len.writeUInt32LE(body.length, 0);
+        process.stdout.write(Buffer.concat([len, body]));
+    };
+    const handle = async (msg) => {
+        switch (msg.cmd) {
+            case 'config':
+                return { ok: true, base: resolveBaseUrl(), token: readToken(), tokenSource: tokenSource(), cli: pkgVersion() };
+            case 'check': {
+                const disk = extInstalledVersion(dir);
+                let latest = '';
+                let error = '';
+                try {
+                    latest = (await extLatestRelease()).version;
+                }
+                catch (e) {
+                    error = String(e.message || e);
+                }
+                return { ok: true, dir, disk, latest, error, cli: pkgVersion() };
+            }
+            case 'update': {
+                const from = extInstalledVersion(dir);
+                if (!from)
+                    return { ok: false, error: `nothing installed at ${dir} — run \`vitrinka extension setup\`` };
+                const rel = await extLatestRelease();
+                if (compareVersions(rel.version, from) <= 0 && msg.force !== true) {
+                    return { ok: true, changed: false, from, to: from };
+                }
+                await extInstallLocked(rel, dir);
+                return { ok: true, changed: true, from, to: rel.version };
+            }
+            default:
+                return { ok: false, error: `unknown cmd ${JSON.stringify(msg.cmd ?? null)}` };
+        }
+    };
+    let buf = Buffer.alloc(0);
+    // Frames are handled one at a time: a second `update` must queue behind the
+    // first, never interleave with its swap.
+    let chain = Promise.resolve();
+    process.stdin.on('data', (chunk) => {
+        buf = Buffer.concat([buf, chunk]);
+        for (;;) {
+            if (buf.length < 4)
+                return;
+            const len = buf.readUInt32LE(0);
+            if (len > EXT_FRAME_MAX) {
+                console.error(`vitrinka extension host: ${len}-byte frame exceeds the 1 MB cap — stream desynced, exiting`);
+                process.exit(1);
+            }
+            if (buf.length < 4 + len)
+                return;
+            const body = buf.subarray(4, 4 + len).toString('utf8');
+            buf = buf.subarray(4 + len);
+            let msg;
+            try {
+                msg = JSON.parse(body);
+            }
+            catch (e) {
+                send({ ok: false, error: `bad JSON frame: ${String(e.message || e)}` });
+                continue;
+            }
+            chain = chain.then(async () => {
+                try {
+                    send(await handle(msg));
+                }
+                catch (e) {
+                    send({ ok: false, error: String(e.message || e) });
+                }
+            });
+        }
+    });
+    // Chrome closes stdin when the port goes away; that is the host's exit signal.
+    await new Promise((res) => { process.stdin.on('end', () => res()); });
+    await chain;
 }
 // ---------- snap: one-shot capture → manifest → detached push ----------
 // Filename slug: diacritics folded (Přihlášení → prihlaseni), non-alnum → '-', capped.
@@ -3597,9 +4518,9 @@ export const COMMANDS = [
         examples: ['vitrinka login', 'vitrinka login --base https://vitrinka.in'],
     },
     {
-        name: 'doctor', summary: 'Check this machine\'s setup (server, token, operator, skills, shim, MCP); --fix repairs it',
+        name: 'doctor', summary: 'Check this machine\'s setup (server, token, operator, skills, shim, MCP, stale listener leases); --fix repairs it',
         usage: '[--fix] [--base <url>]',
-        flags: [{ f: '--fix', d: 'repair everything repairable: refresh skills, rewrite the shim, re-register the MCP, refresh the Claude UI wiring' }, BASE_FLAG],
+        flags: [{ f: '--fix', d: 'repair everything repairable: refresh skills, rewrite the shim, re-register the MCP, refresh the Claude UI wiring, release stale listener leases' }, BASE_FLAG],
         examples: ['vitrinka doctor', 'vitrinka doctor --fix'],
     },
     {
@@ -3610,14 +4531,16 @@ export const COMMANDS = [
         examples: ['vitrinka tidy', 'vitrinka tidy --yes', 'vitrinka tidy --yes --all'],
     },
     {
-        name: 'install', summary: 'Onboard this machine: status table, then skills + shim + completion + MCP + token + operator + Claude UI',
-        usage: '[--local] [--operator <name>] [--mcp|--no-mcp] [--claude|--no-claude] [--no-completion]',
+        name: 'install', summary: 'Onboard this machine: status table, then skills + shim + completion + MCP + token + operator + Claude UI + recorder extension',
+        usage: '[--local] [--operator <name>] [--mcp|--no-mcp] [--claude|--no-claude] [--extension|--no-extension] [--no-completion]',
         flags: [{ f: '--local', d: 'project scope: skills → ./.claude, MCP --scope project; skips shim/completion' },
             { f: '--operator', arg: '<name>', d: 'set the board-attribution persona without prompting' },
             { f: '--mcp', d: 'register the MCP without asking' },
             { f: '--no-mcp', d: 'skip the MCP registration' },
             { f: '--claude', d: 'wire the Claude Code UI without asking' },
             { f: '--no-claude', d: 'skip the Claude Code UI wiring' },
+            { f: '--extension', d: 'install the journey-recorder browser extension without asking (even with no browser detected)' },
+            { f: '--no-extension', d: 'skip the journey-recorder browser extension' },
             { f: '--no-completion', d: 'skip appending the shell-completion line' },
             { f: '--yes', d: 'non-interactive: skip every prompt (config-touchers print their manual command)' }],
         examples: ['vitrinka install', 'vitrinka install --local', 'vitrinka install --operator "Lukáš" --mcp --claude'],
@@ -3645,10 +4568,30 @@ export const COMMANDS = [
         examples: ['vitrinka install-claude'],
     },
     {
-        name: 'update', summary: 'Update the CLI (git pull / npm -g), show what\'s new, refresh the installed plugins + Claude wiring',
-        usage: '[--local]',
-        flags: [{ f: '--local', d: 'refresh skills into ./.claude/skills of the current project instead of ~/.claude/skills' }],
-        examples: ['vitrinka update'],
+        name: 'update', summary: 'Update the CLI (git pull / global install), show what\'s new, refresh the installed plugins + Claude wiring + recorder extension',
+        usage: '[--verbose]',
+        // --local is GONE: it refreshed ~/.claude/skills, and skills have shipped
+        // exclusively as the marketplace plugin since 2026-07-11. It had been a
+        // no-op flag in the help ever since.
+        flags: [{ f: '--verbose', d: 'stream each subprocess\'s full output instead of the live step spinners' }],
+        examples: ['vitrinka update', 'vitrinka update --verbose'],
+    },
+    {
+        name: 'extension', summary: 'Install, update and diagnose the journey-recorder browser extension (in-place updates from the popup)',
+        usage: '<setup|update|doctor> [--check] [--fix] [--force] [--verbose]',
+        positional: '<setup|update|doctor>',
+        flags: [
+            { f: '--check', d: 'update: report whether a release is newer, install nothing' },
+            { f: '--fix', d: 'doctor: re-register the native-messaging host + rewrite the shim' },
+            { f: '--force', d: 'setup/update: re-download even when the installed version is current' },
+            { f: '--verbose', d: 'stream each subprocess\'s full output instead of the live step spinners' },
+        ],
+        examples: [
+            'vitrinka extension setup',
+            'vitrinka extension update',
+            'vitrinka extension update --check',
+            'vitrinka extension doctor --fix',
+        ],
     },
     {
         name: 'version', summary: 'Print the installed version, the install kind, and the last known update state (`--version`/`-V` print the bare version)',
@@ -3704,6 +4647,23 @@ export const COMMANDS = [
         examples: ['vitrinka upload report.pdf --board pr-105-vitrinka --section "Evidence"',
             'vitrinka upload spec.docx shots/*.png --board payout-flow'],
     },
+    {
+        name: 'tag', summary: 'Read and manage the tag vocabulary — the third grouping axis beside project and subgroup',
+        usage: 'ls [--entity board|card|session] | add <board> <tags…> | rm <board> <tags…> | set <board> <tags…> | rename <old> <new> | merge <from> <into> | edit <tag> [--color c] [--icon i] [--desc "…"] | drop <tag>',
+        positional: '<subcommand>',
+        flags: [{ f: '--entity', arg: '<board|card|session>', d: 'ls: only tags carried by that entity type (default: the whole vocabulary)' },
+            { f: '--color', arg: '<name>', d: 'edit: accent colour token' },
+            { f: '--icon', arg: '<name>', d: 'edit: Lucide icon name' },
+            { f: '--desc', arg: '<text>', d: 'edit: what this tag MEANS — returned by list_tags, so agents read it' },
+            { f: '--label', arg: '<text>', d: 'edit: display label (the slug stays the identity)' },
+            { f: '--json', arg: '', d: 'raw JSON instead of the table' },
+            { f: '--yes', arg: '', d: 'confirm merge / drop up front — REQUIRED for them outside a TTY (scripts, CI)' },
+            { f: '--actor', arg: '<name>', d: 'override the operator attribution' }, BASE_FLAG],
+        examples: ['vitrinka tag ls --entity board',
+            'vitrinka tag add pr-105-vitrinka auth "Q3 Launch"',
+            'vitrinka tag merge onbaording onboarding',
+            'vitrinka tag edit auth --color accent --desc "boards covering the auth/login journey"'],
+    },
     {
         name: 'import', summary: 'Parse a source file (OpenAPI / SQL DDL / docker-compose) into a refreshable diagram card',
         usage: '<file> --board <slug> [--kind auto|openapi|sqlddl|compose] [--title "…"] [--section "Name"] [--rev <sha>] [--actor <name>] [--base <url>]',
@@ -4457,6 +5417,184 @@ async function postImport(board, body, args) {
     }
     console.log(text);
 }
+// ---------- tags (tags+spotlight decisions #12) ----------
+// tagApi is the one HTTP seam every `vitrinka tag` subcommand goes through.
+// Returns the parsed body so callers can print a table instead of raw JSON.
+async function tagApi(method, path, args, body) {
+    const base = resolveBaseUrl(strArg(args.base));
+    const headers = {};
+    if (body !== undefined)
+        headers['Content-Type'] = 'application/json';
+    const token = readToken();
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    const actor = actorFor(args);
+    if (actor)
+        headers['X-Board-Actor'] = actor;
+    const res = await fetch(`${base}${path}`, {
+        method, headers,
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        signal: AbortSignal.timeout(30_000),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        console.error(`tag: ${res.status} ${text}`);
+        process.exit(1);
+    }
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // A non-JSON 2xx means we are talking to something that is not the API
+        // (a proxy error page, a login wall) — say so rather than crashing on undefined.
+        console.error(`tag: unexpected non-JSON response: ${text.slice(0, 200)}`);
+        process.exit(1);
+    }
+}
+// printTagTable renders the vocabulary as aligned columns: slug, per-entity
+// counts, and the description that tells a reader what the tag MEANS.
+function printTagTable(tags) {
+    if (!tags.length) {
+        console.log('no tags yet — they autocreate the first time you attach one');
+        return;
+    }
+    const rows = tags.map((t) => {
+        const c = t.counts || {};
+        const counts = ['board', 'card', 'session']
+            .map((k) => (c[k] ? `${c[k]}${k[0]}` : ''))
+            .filter(Boolean).join(' ') || '—';
+        return { slug: t.slug, display: t.display || t.slug, counts, desc: t.description || '' };
+    });
+    const w = (k) => Math.max(...rows.map((r) => r[k].length));
+    const ws = w('slug'), wc = w('counts');
+    for (const r of rows) {
+        const label = r.display !== r.slug ? dim(`  ${r.display}`) : '';
+        console.log(`${r.slug.padEnd(ws)}  ${dim(r.counts.padEnd(wc))}${label}${r.desc ? `  ${dim(r.desc)}` : ''}`);
+    }
+    console.log(dim(`\n${rows.length} tag${rows.length === 1 ? '' : 's'}  ·  b=boards c=cards s=sessions`));
+}
+// reportCreated surfaces the autocreate receipt (decisions #5) — the operator
+// should always see when a command minted a new tag, so a typo is caught at the
+// moment it happens rather than weeks later on the /tags page.
+function reportCreated(created) {
+    const list = Array.isArray(created) ? created.filter((s) => typeof s === 'string') : [];
+    for (const slug of list)
+        console.log(`✦ created new tag: ${slug}`);
+}
+async function tagCmd(rest, args) {
+    // positionals() applies the same greedy rule parseArgs used, so an option
+    // VALUE can never be mistaken for a tag name (tags autocreate — a stray
+    // `--base` URL was being minted as a tag) and a flag placed before the verb
+    // cannot silently select the `ls` default. The hand-rolled
+    // `filter(a => !a.startsWith('--'))` this replaces did both.
+    const argv = positionals(rest);
+    const sub = argv[0] || '';
+    const pos = argv.slice(1);
+    const json = args.json === true;
+    const need = (n, usage) => {
+        if (pos.length < n) {
+            console.error(`usage: vitrinka tag ${usage}`);
+            process.exit(2);
+        }
+        return pos;
+    };
+    // Destructive verbs confirm unless --yes; merge and drop both change what
+    // other boards are tagged with, so they are never silent.
+    //
+    // Fails CLOSED without a TTY: treating "cannot ask" as "yes" meant `drop`
+    // (which detaches the tag from every board, card and session) ran unconfirmed
+    // in CI, scripts, and any redirected shell — the opposite of what --yes
+    // documents, and of what uninstallCmd does in the same file.
+    const confirm = async (what) => {
+        if (args.yes === true)
+            return;
+        if (!process.stdin.isTTY) {
+            console.error(`tag: refusing to ${what} without a TTY to confirm on — re-run with --yes`);
+            process.exit(2);
+        }
+        const ok = await confirmYN(`${what} — continue?`);
+        if (!ok) {
+            console.log('aborted');
+            process.exit(0);
+        }
+    };
+    switch (sub) {
+        case 'ls':
+        case '': {
+            const entity = strArg(args.entity);
+            const q = entity ? `?entity=${encodeURIComponent(entity)}` : '';
+            const data = await tagApi('GET', `/api/v1/tags${q}`, args);
+            if (json) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            printTagTable(data?.tags || []);
+            return;
+        }
+        case 'add':
+        case 'rm':
+        case 'set': {
+            const [board, ...names] = need(2, `${sub} <board> <tags…>`);
+            if (sub === 'rm') {
+                const data = await tagApi('DELETE', `/api/v1/boards/${encodeURIComponent(board)}/tags?tags=${encodeURIComponent(names.join(','))}`, args);
+                console.log(json ? JSON.stringify(data, null, 2)
+                    : `${board}: ${(data?.tags || []).map((t) => t.slug).join(' ') || '(no tags)'}`);
+                return;
+            }
+            const data = await tagApi('POST', `/api/v1/boards/${encodeURIComponent(board)}/tags`, args, { tags: names, ...(sub === 'set' ? { mode: 'set' } : {}) });
+            if (json) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            reportCreated(data?.created);
+            console.log(`${board}: ${(data?.tags || []).map((t) => t.slug).join(' ') || '(no tags)'}`);
+            return;
+        }
+        case 'rename': {
+            const [from, to] = need(2, 'rename <old> <new>');
+            const data = await tagApi('PATCH', `/api/v1/tags/${encodeURIComponent(from)}`, args, { name: to });
+            console.log(json ? JSON.stringify(data, null, 2) : `${from} → ${data?.tag?.slug}`);
+            return;
+        }
+        case 'merge': {
+            const [from, into] = need(2, 'merge <from> <into>');
+            await confirm(`merge "${from}" into "${into}" (every board tagged ${from} moves, ${from} is deleted)`);
+            const data = await tagApi('POST', `/api/v1/tags/${encodeURIComponent(from)}/merge`, args, { into });
+            console.log(json ? JSON.stringify(data, null, 2)
+                : `merged ${from} → ${data?.tag?.slug} (${data?.moved ?? 0} attachment${data?.moved === 1 ? '' : 's'} moved)`);
+            return;
+        }
+        case 'edit': {
+            const [slug] = need(1, 'edit <tag> [--label "…"] [--color c] [--icon i] [--desc "…"]');
+            const patch = {};
+            for (const [flag, key] of [['label', 'label'], ['color', 'color'], ['icon', 'icon'], ['desc', 'description']]) {
+                const v = args[flag];
+                if (v !== undefined)
+                    patch[key] = typeof v === 'string' ? v : String(v);
+            }
+            if (!Object.keys(patch).length) {
+                console.error('usage: vitrinka tag edit <tag> [--label "…"] [--color c] [--icon i] [--desc "…"]');
+                process.exit(2);
+            }
+            const data = await tagApi('PATCH', `/api/v1/tags/${encodeURIComponent(slug)}`, args, patch);
+            console.log(json ? JSON.stringify(data, null, 2) : `${data?.tag?.slug} updated`);
+            return;
+        }
+        case 'drop': {
+            const [slug] = need(1, 'drop <tag>');
+            await confirm(`delete "${slug}" (it is detached from every board, card and session carrying it)`);
+            await tagApi('DELETE', `/api/v1/tags/${encodeURIComponent(slug)}`, args);
+            console.log(`dropped ${slug}`);
+            return;
+        }
+        default:
+            console.error(`tag: unknown subcommand ${JSON.stringify(sub)}\n`
+                + 'usage: vitrinka tag ls | add | rm | set | rename | merge | edit | drop');
+            process.exit(2);
+    }
+}
 async function importCmd(rest, args) {
     const file = rest.find((a) => !a.startsWith('--'));
     const board = strArg(args.board);
@@ -4665,6 +5803,28 @@ export function computeChoiceAnnouncements(prev, choices) {
 export function shouldKeepalive(nowMs, lastWakeMs, keepaliveSec, viewerPresent) {
     return keepaliveSec > 0 && viewerPresent && nowMs - lastWakeMs >= keepaliveSec * 1000;
 }
+// isOrphaned is the parent-death guard (PURE — unit-tested). The watch leases
+// its scope through the long-poll, so a watch that outlives its agent session
+// keeps the lease ALIVE forever: the TTL only reaps leases that stop
+// heartbeating, and an orphan never stops. The scope then belongs to a process
+// whose stdout nobody reads and dispatched work vanishes into it.
+//
+// A signal can't be relied on to prevent that. Claude Code SIGTERMs the shell
+// it spawned, so `exec vitrinka watch` (what the listen skill arms) does get
+// the signal — but a SIGKILLed / crashed / terminal-closed agent never sends
+// one, and a non-exec wrapper eats it. The universal tell is REPARENTING: any
+// change to our ppid means the process that started us is gone (adopted by
+// init, or by a subreaper). We were born attached; we are now not.
+//
+// A watch deliberately started detached (nohup, launchd, systemd, a container
+// entrypoint) is born with a stable ppid and never sees it change — so it is
+// never touched by this guard.
+export function isOrphaned(bornPpid, currentPpid) {
+    return bornPpid > 1 && currentPpid !== bornPpid;
+}
+// How often the persistent watch checks for reparenting. `process.ppid` is a
+// live syscall (uv_os_getppid), not a cached boot value.
+const WATCH_ORPHAN_POLL_MS = 5_000;
 const watchEmit = (line) => { process.stdout.write(line + '\n'); };
 const watchSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function watchBaseUrl(args) {
@@ -4807,8 +5967,22 @@ async function watchCmd(args) {
         }
         process.exit(code);
     };
+    // SIGHUP too: closing the terminal that hosts the agent hangs us up, and a
+    // hangup must release the lease exactly like an interrupt.
     process.on('SIGINT', () => { void shutdown(0); });
     process.on('SIGTERM', () => { void shutdown(0); });
+    process.on('SIGHUP', () => { void shutdown(0); });
+    // Parent-death guard — the backstop for every exit that delivers no signal
+    // (agent SIGKILLed, crashed, or its wrapper shell absorbed the SIGTERM).
+    // unref'd so it never keeps the process alive on its own.
+    const bornPpid = process.ppid;
+    setInterval(() => {
+        if (!isOrphaned(bornPpid, process.ppid))
+            return;
+        // stderr: the Monitor records it without waking a session that is already gone.
+        process.stderr.write(`vitrinka watch: parent ${bornPpid} exited — releasing ${scope.label} and stopping\n`);
+        void shutdown(0);
+    }, WATCH_ORPHAN_POLL_MS).unref();
     let announced = {};
     let announcedChoices = {};
     let downSince = null;
@@ -4970,6 +6144,8 @@ async function runSub(argv) {
         uninstallCmd(args);
     else if (cmd === 'update')
         await updateCmd(args);
+    else if (cmd === 'extension')
+        await extensionCmd(rest, args);
     else if (cmd === 'version')
         versionCmd(false);
     else if (cmd === 'open')
@@ -4984,6 +6160,8 @@ async function runSub(argv) {
         await uploadCmd(rest, args);
     else if (cmd === 'import')
         await importCmd(rest, args);
+    else if (cmd === 'tag')
+        await tagCmd(rest, args);
     else if (cmd === 'schema')
         await schemaCmd(rest, args);
     else if (cmd === 'board-from-set')