@jackwener/opencli 1.7.9 → 1.7.11

package/dist/src/build-manifest.d.ts

@@ -5,41 +5,76 @@
  * Scans all JS CLI definitions in clis/ and pre-compiles them into a single
  * manifest.json for instant cold-start registration.
  *
- * Usage: npx tsx src/build-manifest.ts
+ * Usage: npx tsx src/build-manifest.ts [--allow-removals[=N]]
+ *
  * Output: cli-manifest.json next to clis/
+ *
+ * Safety invariants:
+ *   - Adapters whose source file does not call `cli(...)` are silently
+ *     skipped (they are helpers / type modules, not commands).
+ *   - Adapters that look like commands but fail to import are reported as
+ *     failures, the manifest is NOT written, and the process exits 1. This
+ *     prevents a stale dist or a broken adapter from silently dropping
+ *     other adapters' entries (root cause of the "manifest lost 478 lines"
+ *     incident).
+ *   - Net-deletions vs the existing committed manifest abort the build by
+ *     default; pass `--allow-removals=N` (or just `--allow-removals` for any
+ *     amount) to confirm an intentional removal.
+ */
+import type { ManifestEntry } from './manifest-types.js';
+export type { ManifestEntry } from './manifest-types.js';
+/**
+ * Thrown by `loadManifestEntries` when an adapter file looks like a CLI
+ * module (matches CLI_MODULE_PATTERN) but cannot be imported. Callers
+ * decide whether to abort or aggregate failures across the whole scan.
  */
-export interface ManifestEntry {
-    site: string;
-    name: string;
-    aliases?: string[];
-    description: string;
-    domain?: string;
-    strategy: string;
-    browser: boolean;
-    args: Array<{
-        name: string;
-        type?: string;
-        default?: unknown;
-        required?: boolean;
-        valueRequired?: boolean;
-        positional?: boolean;
-        help?: string;
-        choices?: string[];
-    }>;
-    columns?: string[];
-    pipeline?: Record<string, unknown>[];
-    timeout?: number;
-    deprecated?: boolean | string;
-    replacedBy?: string;
-    type: 'js';
-    /** Relative path from clis/ dir, e.g. 'bilibili/search.js' */
-    modulePath?: string;
-    /** Relative path to the source file from clis/ dir (e.g. 'site/cmd.js') */
-    sourceFile?: string;
-    /** Pre-navigation control — see CliCommand.navigateBefore */
-    navigateBefore?: boolean | string;
+export declare class ManifestImportError extends Error {
+    readonly filePath: string;
+    readonly cause: unknown;
+    constructor(filePath: string, cause: unknown);
+}
+export interface BuildManifestResult {
+    entries: ManifestEntry[];
+    /** Adapters that look like CLI modules but failed to import. */
+    failures: ManifestImportError[];
+}
+export interface BuildManifestArgs {
+    /** Maximum number of entries that may be removed vs the existing manifest.
+     *  `Number.POSITIVE_INFINITY` disables the safety net entirely. */
+    allowRemovals: number;
 }
 export declare function normalizeManifestPath(relativePath: string): string;
-export declare function loadManifestEntries(filePath: string, site: string, importer?: (moduleHref: string) => Promise<unknown>): Promise<ManifestEntry[]>;
-export declare function buildManifest(): Promise<ManifestEntry[]>;
+/**
+ * Load all manifest entries from a single adapter file.
+ *
+ * Returns `[]` for files that do not register a CLI command (helpers, types).
+ * Throws `ManifestImportError` when a file looks like a CLI module but its
+ * import or post-import processing fails — callers must decide whether to
+ * surface or aggregate the failure.
+ *
+ * The third argument `clisDir` is used to compute the POSIX-style
+ * `sourceFile` relative path; it defaults to the package's `clis/` dir so
+ * existing test callers stay backward-compatible.
+ */
+export declare function loadManifestEntries(filePath: string, site: string, importer?: (moduleHref: string) => Promise<unknown>, clisDir?: string): Promise<ManifestEntry[]>;
+/**
+ * Scan a `clis/` directory and aggregate per-adapter results. Import
+ * failures are collected in `failures` instead of crashing the whole scan,
+ * but the caller (e.g. `main()`) is expected to fail loud if any failure
+ * is present.
+ */
+export declare function scanClisDir(clisDir: string, importer?: (moduleHref: string) => Promise<unknown>): Promise<BuildManifestResult>;
+export declare function buildManifest(): Promise<BuildManifestResult>;
 export declare function serializeManifest(manifest: ManifestEntry[]): string;
+/**
+ * Diff helper: returns site/name keys that exist in `prev` but not in
+ * `next`. Used as a safety net to detect accidental mass-deletions caused
+ * by silently failing adapter imports.
+ */
+export declare function diffRemovedEntries(prev: readonly ManifestEntry[], next: readonly ManifestEntry[]): string[];
+/**
+ * Parse `--allow-removals` and `--allow-removals=N` from argv.
+ * Bare `--allow-removals` disables the safety net (`Infinity`); the
+ * numeric form sets an explicit upper bound.
+ */
+export declare function parseBuildManifestArgs(argv: readonly string[]): BuildManifestArgs;

package/dist/src/build-manifest.js

@@ -5,8 +5,21 @@
  * Scans all JS CLI definitions in clis/ and pre-compiles them into a single
  * manifest.json for instant cold-start registration.
  *
- * Usage: npx tsx src/build-manifest.ts
+ * Usage: npx tsx src/build-manifest.ts [--allow-removals[=N]]
+ *
  * Output: cli-manifest.json next to clis/
+ *
+ * Safety invariants:
+ *   - Adapters whose source file does not call `cli(...)` are silently
+ *     skipped (they are helpers / type modules, not commands).
+ *   - Adapters that look like commands but fail to import are reported as
+ *     failures, the manifest is NOT written, and the process exits 1. This
+ *     prevents a stale dist or a broken adapter from silently dropping
+ *     other adapters' entries (root cause of the "manifest lost 478 lines"
+ *     incident).
+ *   - Net-deletions vs the existing committed manifest abort the build by
+ *     default; pass `--allow-removals=N` (or just `--allow-removals` for any
+ *     amount) to confirm an intentional removal.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -14,12 +27,27 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { getErrorMessage } from './errors.js';
 import { fullName, getRegistry } from './registry.js';
 import { findPackageRoot, getCliManifestPath } from './package-paths.js';
+import { isRecord } from './utils.js';
 const PACKAGE_ROOT = findPackageRoot(fileURLToPath(import.meta.url));
 const CLIS_DIR = path.join(PACKAGE_ROOT, 'clis');
 // Write manifest next to clis/ so both dev and installed runtime can find it.
 const OUTPUT = getCliManifestPath(CLIS_DIR);
-import { isRecord } from './utils.js';
 const CLI_MODULE_PATTERN = /\bcli\s*\(/;
+/**
+ * Thrown by `loadManifestEntries` when an adapter file looks like a CLI
+ * module (matches CLI_MODULE_PATTERN) but cannot be imported. Callers
+ * decide whether to abort or aggregate failures across the whole scan.
+ */
+export class ManifestImportError extends Error {
+    filePath;
+    cause;
+    constructor(filePath, cause) {
+        super(`failed to scan ${filePath}: ${getErrorMessage(cause)}`);
+        this.filePath = filePath;
+        this.cause = cause;
+        this.name = 'ManifestImportError';
+    }
+}
 function toManifestArgs(args) {
     return args.map(arg => ({
         name: arg.name,
@@ -39,8 +67,8 @@ function toModulePath(filePath, site) {
 export function normalizeManifestPath(relativePath) {
     return relativePath.replace(/\\/g, '/');
 }
-function toManifestRelativePath(filePath) {
-    return normalizeManifestPath(path.relative(CLIS_DIR, filePath));
+function toManifestRelativePath(filePath, clisDir) {
+    return normalizeManifestPath(path.relative(clisDir, filePath));
 }
 function isCliCommandValue(value, site) {
     return isRecord(value)
@@ -69,12 +97,30 @@ function toManifestEntry(cmd, modulePath, sourceFile) {
         navigateBefore: cmd.navigateBefore,
     };
 }
-export async function loadManifestEntries(filePath, site, importer = moduleHref => import(moduleHref)) {
+/**
+ * Load all manifest entries from a single adapter file.
+ *
+ * Returns `[]` for files that do not register a CLI command (helpers, types).
+ * Throws `ManifestImportError` when a file looks like a CLI module but its
+ * import or post-import processing fails — callers must decide whether to
+ * surface or aggregate the failure.
+ *
+ * The third argument `clisDir` is used to compute the POSIX-style
+ * `sourceFile` relative path; it defaults to the package's `clis/` dir so
+ * existing test callers stay backward-compatible.
+ */
+export async function loadManifestEntries(filePath, site, importer = moduleHref => import(moduleHref), clisDir = CLIS_DIR) {
+    let src;
+    try {
+        src = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        throw new ManifestImportError(filePath, err);
+    }
+    // Helper / test modules that do not call cli() are not commands.
+    if (!CLI_MODULE_PATTERN.test(src))
+        return [];
     try {
-        const src = fs.readFileSync(filePath, 'utf-8');
-        // Helper/test modules should not appear as CLI commands in the manifest.
-        if (!CLI_MODULE_PATTERN.test(src))
-            return [];
         const modulePath = toModulePath(filePath, site);
         const registry = getRegistry();
         const before = new Map(registry.entries());
@@ -93,7 +139,7 @@ export async function loadManifestEntries(filePath, site, importer = moduleHref
                 .map(([, cmd]) => cmd);
         // Manifest paths are cross-platform artifacts; keep them POSIX-style even
         // when build-manifest runs on Windows.
-        const sourceRelative = toManifestRelativePath(filePath);
+        const sourceRelative = toManifestRelativePath(filePath, clisDir);
         const seen = new Set();
         return runtimeCommands
             .filter((cmd) => {
@@ -107,42 +153,142 @@ export async function loadManifestEntries(filePath, site, importer = moduleHref
             .map(cmd => toManifestEntry(cmd, modulePath, sourceRelative));
     }
     catch (err) {
-        // If parsing fails, log a warning (matching scanYaml behaviour) and skip the entry.
-        process.stderr.write(`Warning: failed to scan ${filePath}: ${getErrorMessage(err)}\n`);
-        return [];
+        throw new ManifestImportError(filePath, err);
     }
 }
-export async function buildManifest() {
+/**
+ * Scan a `clis/` directory and aggregate per-adapter results. Import
+ * failures are collected in `failures` instead of crashing the whole scan,
+ * but the caller (e.g. `main()`) is expected to fail loud if any failure
+ * is present.
+ */
+export async function scanClisDir(clisDir, importer = moduleHref => import(moduleHref)) {
     const manifest = new Map();
-    // Scan JS adapters directly from clis/.
-    // Adapters are now JS-first — no compilation step needed.
-    if (fs.existsSync(CLIS_DIR)) {
-        for (const site of fs.readdirSync(CLIS_DIR)) {
-            const siteDir = path.join(CLIS_DIR, site);
-            if (!fs.statSync(siteDir).isDirectory())
-                continue;
-            for (const file of fs.readdirSync(siteDir)) {
-                if (file.endsWith('.js') && !file.endsWith('.d.js') && !file.endsWith('.test.js') && file !== 'index.js') {
-                    const filePath = path.join(siteDir, file);
-                    const entries = await loadManifestEntries(filePath, site);
+    const failures = [];
+    if (!fs.existsSync(clisDir)) {
+        return { entries: [], failures };
+    }
+    for (const site of fs.readdirSync(clisDir)) {
+        const siteDir = path.join(clisDir, site);
+        if (!fs.statSync(siteDir).isDirectory())
+            continue;
+        for (const file of fs.readdirSync(siteDir)) {
+            if (file.endsWith('.js') && !file.endsWith('.d.js') && !file.endsWith('.test.js') && file !== 'index.js') {
+                const filePath = path.join(siteDir, file);
+                try {
+                    const entries = await loadManifestEntries(filePath, site, importer, clisDir);
                     for (const entry of entries) {
                         const key = `${entry.site}/${entry.name}`;
                         manifest.set(key, entry);
                     }
                 }
+                catch (err) {
+                    if (err instanceof ManifestImportError) {
+                        failures.push(err);
+                        continue;
+                    }
+                    throw err;
+                }
             }
         }
     }
-    return [...manifest.values()].sort((a, b) => a.site.localeCompare(b.site) || a.name.localeCompare(b.name));
+    const entries = [...manifest.values()].sort((a, b) => a.site.localeCompare(b.site) || a.name.localeCompare(b.name));
+    return { entries, failures };
+}
+export async function buildManifest() {
+    return scanClisDir(CLIS_DIR);
 }
 export function serializeManifest(manifest) {
     return `${JSON.stringify(manifest, null, 2)}\n`;
 }
+/**
+ * Diff helper: returns site/name keys that exist in `prev` but not in
+ * `next`. Used as a safety net to detect accidental mass-deletions caused
+ * by silently failing adapter imports.
+ */
+export function diffRemovedEntries(prev, next) {
+    const nextKeys = new Set(next.map(e => `${e.site}/${e.name}`));
+    return prev
+        .map(e => `${e.site}/${e.name}`)
+        .filter(key => !nextKeys.has(key))
+        .sort();
+}
+/**
+ * Parse `--allow-removals` and `--allow-removals=N` from argv.
+ * Bare `--allow-removals` disables the safety net (`Infinity`); the
+ * numeric form sets an explicit upper bound.
+ */
+export function parseBuildManifestArgs(argv) {
+    let allowRemovals = 0;
+    for (const arg of argv) {
+        if (arg === '--allow-removals') {
+            allowRemovals = Number.POSITIVE_INFINITY;
+            continue;
+        }
+        const m = arg.match(/^--allow-removals=(\d+)$/);
+        if (m) {
+            allowRemovals = Number.parseInt(m[1], 10);
+            continue;
+        }
+    }
+    return { allowRemovals };
+}
+function readExistingManifest(filePath) {
+    try {
+        if (!fs.existsSync(filePath))
+            return null;
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
 async function main() {
-    const manifest = await buildManifest();
+    // Runtime guard: refuse to run from dist/. tsc transitively emits this
+    // file (the test file imports from it) so dist/src/build-manifest.js
+    // physically exists. If a developer or agent runs that compiled copy,
+    // any stale dist will silently break adapter imports — the exact failure
+    // mode this script is meant to prevent. Direct them at the tsx entry
+    // before they can shoot themselves in the foot.
+    if (fileURLToPath(import.meta.url).includes(`${path.sep}dist${path.sep}`)) {
+        process.stderr.write(`❌ Refusing to run build-manifest from dist/.\n`
+            + `   Stale compiled output silently drops adapters that import renamed/removed exports.\n`
+            + `   Run \`npm run build-manifest\` (or \`tsx src/build-manifest.ts\`) from the source tree instead.\n`);
+        process.exit(1);
+    }
+    const args = parseBuildManifestArgs(process.argv.slice(2));
+    const { entries, failures } = await buildManifest();
+    if (failures.length > 0) {
+        process.stderr.write(`❌ ${failures.length} adapter(s) failed to load:\n`);
+        for (const failure of failures) {
+            const rel = path.relative(PACKAGE_ROOT, failure.filePath) || failure.filePath;
+            process.stderr.write(`  - ${rel}: ${getErrorMessage(failure.cause)}\n`);
+        }
+        process.stderr.write(`\nManifest NOT written. Likely cause: stale dist/ or a broken adapter import.\n`
+            + `Always run via tsx (\`npm run build-manifest\`), not against compiled dist/.\n`);
+        process.exit(1);
+    }
+    const existing = readExistingManifest(OUTPUT);
+    if (existing) {
+        const removed = diffRemovedEntries(existing, entries);
+        if (removed.length > args.allowRemovals) {
+            process.stderr.write(`❌ ${removed.length} manifest entries would be removed; refusing to overwrite.\n`);
+            const preview = removed.slice(0, 20);
+            for (const key of preview)
+                process.stderr.write(`  - ${key}\n`);
+            if (removed.length > preview.length) {
+                process.stderr.write(`  ... ${removed.length - preview.length} more\n`);
+            }
+            process.stderr.write(`\nIf this removal is intentional, rerun with `
+                + `\`--allow-removals=${removed.length}\` (or \`--allow-removals\` to disable the check).\n`);
+            process.exit(1);
+        }
+    }
     fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
-    fs.writeFileSync(OUTPUT, serializeManifest(manifest));
-    console.log(`✅ Manifest compiled: ${manifest.length} entries → ${OUTPUT}`);
+    fs.writeFileSync(OUTPUT, serializeManifest(entries));
+    console.log(`✅ Manifest compiled: ${entries.length} entries → ${OUTPUT}`);
     // Restore executable permissions on bin entries.
     // tsc does not preserve the +x bit, so after a clean rebuild the CLI
     // entry-point loses its executable permission, causing "Permission denied".

package/dist/src/build-manifest.test.js

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { cli, getRegistry, Strategy } from './registry.js';
-import { loadManifestEntries, normalizeManifestPath, serializeManifest } from './build-manifest.js';
+import { ManifestImportError, diffRemovedEntries, loadManifestEntries, normalizeManifestPath, parseBuildManifestArgs, scanClisDir, serializeManifest, } from './build-manifest.js';
 describe('manifest helper rules', () => {
     const tempDirs = [];
     afterEach(() => {
@@ -157,4 +157,78 @@ describe('manifest helper rules', () => {
         expect(serialized.endsWith('\n')).toBe(true);
         expect(serialized).toContain('\n]');
     });
+    it('throws ManifestImportError when an adapter looks like a CLI module but fails to import', async () => {
+        // Reproduces the "stale dist drops adapters silently" incident: the file
+        // matches the cli() pattern (so it's not just a helper), but the importer
+        // throws — we want the failure surfaced, not swallowed.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-fail-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, 'broken.ts');
+        fs.writeFileSync(file, `export const command = cli({ site: 'demo', name: 'broken' });`);
+        const importer = async () => { throw new Error('boom: stale dist'); };
+        await expect(loadManifestEntries(file, 'demo', importer))
+            .rejects.toBeInstanceOf(ManifestImportError);
+        try {
+            await loadManifestEntries(file, 'demo', importer);
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ManifestImportError);
+            const e = err;
+            expect(e.filePath).toBe(file);
+            expect(e.message).toContain('boom: stale dist');
+        }
+    });
+    it('still silently skips files that do not call cli() even if the importer would have thrown', async () => {
+        // The cli() pattern check happens before importing — we don't even ask
+        // the importer about helper modules, so a thrown import does not turn
+        // them into failures.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-helper-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, 'helper.ts');
+        fs.writeFileSync(file, `export const helper = () => 42;`);
+        const importer = async () => { throw new Error('should never be called'); };
+        await expect(loadManifestEntries(file, 'demo', importer)).resolves.toEqual([]);
+    });
+    it('scanClisDir aggregates per-adapter import failures instead of silently dropping them', async () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-clis-'));
+        tempDirs.push(root);
+        const siteDir = path.join(root, 'demo');
+        fs.mkdirSync(siteDir);
+        fs.writeFileSync(path.join(siteDir, 'good.js'), `export const cmd = cli({ site: 'demo', name: 'good' });`);
+        fs.writeFileSync(path.join(siteDir, 'broken.js'), `export const cmd = cli({ site: 'demo', name: 'broken' });`);
+        const importer = async (href) => {
+            if (href.endsWith('broken.js'))
+                throw new Error('stale dist drops broken');
+            return { cmd: cli({ site: 'demo', name: 'good', description: 'ok' }) };
+        };
+        const result = await scanClisDir(root, importer);
+        expect(result.failures).toHaveLength(1);
+        expect(result.failures[0]).toBeInstanceOf(ManifestImportError);
+        expect(result.failures[0].filePath).toMatch(/broken\.js$/);
+        expect(result.failures[0].message).toContain('stale dist drops broken');
+        expect(result.entries.map(e => e.name)).toEqual(['good']);
+        getRegistry().delete('demo/good');
+    });
+    it('diffRemovedEntries returns site/name keys present only in prev', () => {
+        const prev = [
+            { site: 'a', name: '1', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+            { site: 'a', name: '2', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+            { site: 'b', name: '3', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+        ];
+        const next = [
+            { site: 'a', name: '1', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+        ];
+        expect(diffRemovedEntries(prev, next)).toEqual(['a/2', 'b/3']);
+        expect(diffRemovedEntries(prev, prev)).toEqual([]);
+        expect(diffRemovedEntries([], next)).toEqual([]);
+    });
+    it('parseBuildManifestArgs reads --allow-removals[=N]', () => {
+        expect(parseBuildManifestArgs([]).allowRemovals).toBe(0);
+        expect(parseBuildManifestArgs(['--allow-removals=5']).allowRemovals).toBe(5);
+        expect(parseBuildManifestArgs(['--allow-removals=0']).allowRemovals).toBe(0);
+        // Bare flag is the explicit "I know what I'm doing" escape hatch.
+        expect(parseBuildManifestArgs(['--allow-removals']).allowRemovals).toBe(Number.POSITIVE_INFINITY);
+        // Unknown flags are ignored.
+        expect(parseBuildManifestArgs(['--something-else']).allowRemovals).toBe(0);
+    });
 });

package/dist/src/cli.js

@@ -29,10 +29,11 @@ import { parseFilter, shapeMatchesFilter } from './browser/shape-filter.js';
 import { buildHtmlTreeJs } from './browser/html-tree.js';
 import { buildExtractHtmlJs, runExtractFromHtml } from './browser/extract.js';
 import { analyzeSite } from './browser/analyze.js';
-import { daemonStatus, daemonStop } from './commands/daemon.js';
+import { daemonRestart, daemonStatus, daemonStop } from './commands/daemon.js';
 import { log } from './logger.js';
 import { bindTab, BrowserCommandError, fetchDaemonStatus, sendCommand } from './browser/daemon-client.js';
 import { aliasForContextId, loadProfileConfig, renameProfile, resolveProfileContextId, setDefaultProfile } from './browser/profile.js';
+import { formatDaemonVersion, isDaemonStale } from './browser/daemon-version.js';
 const CLI_FILE = fileURLToPath(import.meta.url);
 const DEFAULT_BROWSER_WORKSPACE = 'browser:default';
 const DEFAULT_BOUND_WORKSPACE = 'bound:default';
@@ -1758,6 +1759,7 @@ cli({
             fs.mkdirSync(dir, { recursive: true });
             fs.writeFileSync(filePath, template, 'utf-8');
             console.log(`Created: ${filePath}`);
+            console.log('First time on this site? Run: opencli browser analyze <url>');
             console.log(`Edit the file to implement your adapter, then run: opencli browser verify ${name}`);
         }
         catch (err) {
@@ -1772,6 +1774,8 @@ cli({
         .option('--update-fixture', 'Overwrite an existing fixture with one derived from current output')
         .option('--no-fixture', 'Ignore any fixture file for this run (no value-level validation)')
         .option('--strict-memory', 'Fail (not just warn) when ~/.opencli/sites/<site>/endpoints.json or notes.md is missing')
+        .option('--seed-args <value>', 'Seed args when no fixture exists; use JSON array/object for multiple args or flags')
+        .option('--trace <mode>', 'Trace capture for the adapter subprocess: off, on, retain-on-failure', 'off')
         .description('Execute an adapter and validate output; uses fixture at ~/.opencli/sites/<site>/verify/<cmd>.json when present')
         .action(async (name, opts = {}) => {
         try {
@@ -1788,7 +1792,7 @@ cli({
                 return;
             }
             const { execFileSync } = await import('node:child_process');
-            const { loadFixture, writeFixture, deriveFixture, validateRows, fixturePath, expandFixtureArgs } = await import('./browser/verify-fixture.js');
+            const { loadFixture, writeFixture, deriveFixture, validateRows, fixturePath, expandFixtureArgs, parseSeedArgs } = await import('./browser/verify-fixture.js');
             const filePath = path.join(os.homedir(), '.opencli', 'clis', site, `${command}.js`);
             if (!fs.existsSync(filePath)) {
                 console.error(`Adapter not found: ${filePath}`);
@@ -1805,14 +1809,16 @@ cli({
             //   - array form    ["123", "--limit", "3"]   → verbatim (for positional subjects)
             const adapterSrc = fs.readFileSync(filePath, 'utf-8');
             const hasLimitArg = /['"]limit['"]/.test(adapterSrc);
-            const fixtureArgs = fixture?.args;
-            const cliArgs = expandFixtureArgs(fixtureArgs);
-            if (cliArgs.length === 0 && hasLimitArg)
+            const seedArgs = parseSeedArgs(opts.seedArgs);
+            const explicitArgs = fixture?.args ?? seedArgs;
+            const cliArgs = expandFixtureArgs(explicitArgs);
+            if (explicitArgs === undefined && cliArgs.length === 0 && hasLimitArg)
                 cliArgs.push('--limit', '3');
-            const argDisplay = cliArgs.join(' ');
+            const traceArgs = opts.trace && opts.trace !== 'off' ? ['--trace', opts.trace] : [];
+            const argDisplay = [...cliArgs, ...traceArgs].join(' ');
             const invocation = resolveBrowserVerifyInvocation();
             // Always request JSON so we can validate structurally.
-            const execArgs = [...invocation.args, site, command, ...cliArgs, '--format', 'json'];
+            const execArgs = [...invocation.args, site, command, ...cliArgs, ...traceArgs, '--format', 'json'];
             let rawJson;
             try {
                 rawJson = execFileSync(invocation.binary, execArgs, {
@@ -1855,10 +1861,10 @@ cli({
                     console.log(`  Use --update-fixture to overwrite.`);
                 }
                 else {
-                    const seedArgs = fixtureArgs !== undefined
-                        ? fixtureArgs
+                    const fixtureArgs = explicitArgs !== undefined
+                        ? explicitArgs
                         : (hasLimitArg ? { limit: 3 } : undefined);
-                    const derived = deriveFixture(rows, seedArgs);
+                    const derived = deriveFixture(rows, fixtureArgs);
                     const p = writeFixture(site, command, derived);
                     console.log(`\n  ${fixture ? '↻ Updated' : '✎ Wrote'} fixture: ${p}`);
                     console.log(`  Review and hand-tune the derived expectations (add patterns / notEmpty, tighten rowCount).`);
@@ -2232,6 +2238,11 @@ cli({
             console.log(styleText('yellow', 'Daemon is not running. Run opencli doctor after opening Chrome.'));
             return;
         }
+        if (isDaemonStale(status, PKG_VERSION) || !Array.isArray(status.profiles)) {
+            console.log(styleText('yellow', `Daemon ${formatDaemonVersion(status)} is stale for CLI v${PKG_VERSION}.`));
+            console.log(styleText('dim', 'Run: opencli daemon restart'));
+            return;
+        }
         if (profiles.length === 0) {
             console.log(styleText('yellow', 'No Browser Bridge profiles connected.'));
             console.log(styleText('dim', 'Open a Chrome profile with the OpenCLI extension installed, then run opencli profile list again.'));
@@ -2301,6 +2312,10 @@ cli({
         .command('stop')
         .description('Stop the daemon')
         .action(async () => { await daemonStop(); });
+    daemonCmd
+        .command('restart')
+        .description('Restart the daemon')
+        .action(async () => { await daemonRestart(); });
     // ── External CLIs ─────────────────────────────────────────────────────────
     const externalClis = loadExternalClis();
     const externalCmd = program