@agentrhq/webcmd 0.2.0 → 0.2.2

package/dist/src/browser/runtime/local-cloak/session-manager.test.js

@@ -1,5 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
+import path from 'node:path';
 import { CloakSessionManager } from './session-manager.js';
+import { dispatchCloakAction } from './actions.js';
 function fakeContext() {
     const page = {
         goto: vi.fn().mockResolvedValue(undefined),
@@ -20,6 +22,9 @@ function fakeContext() {
         page,
     };
 }
+function expectedProfileDir(profileId) {
+    return path.join('/tmp/webcmd-test', 'cloak', 'profiles', profileId);
+}
 describe('CloakSessionManager', () => {
     afterEach(() => {
         vi.useRealTimers();
@@ -37,6 +42,64 @@ describe('CloakSessionManager', () => {
         expect(launchPersistentContext).toHaveBeenCalledTimes(1);
         expect(launchPersistentContext.mock.calls[0][0]).toMatchObject({ headless: false });
     });
+    it('freshPage closes the existing persistent lease page and creates a new one', async () => {
+        const makePage = () => ({
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue('ok'),
+            title: vi.fn().mockResolvedValue('Title'),
+            url: vi.fn().mockReturnValue('about:blank'),
+            isClosed: vi.fn().mockReturnValue(false),
+            close: vi.fn().mockResolvedValue(undefined),
+        });
+        const openPages = [];
+        const context = {
+            pages: vi.fn(() => openPages),
+            newPage: vi.fn(async () => {
+                const page = makePage();
+                openPages.push(page);
+                return page;
+            }),
+            cookies: vi.fn().mockResolvedValue([]),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(context),
+        });
+        const key = { profileId: 'default', session: 'site:district', surface: 'adapter', siteSession: 'persistent' };
+        const first = await manager.getPage(key);
+        expect((await manager.getPage(key)).page).toBe(first.page);
+        const fresh = await manager.getPage({ ...key, freshPage: true });
+        expect(first.page.close).toHaveBeenCalled();
+        expect(fresh.page).not.toBe(first.page);
+        const reused = await manager.getPage(key);
+        expect(reused.page).toBe(fresh.page);
+    });
+    it('freshPage never adopts a leftover context tab', async () => {
+        const leftover = {
+            goto: vi.fn(),
+            isClosed: vi.fn().mockReturnValue(false),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const created = {
+            goto: vi.fn(),
+            isClosed: vi.fn().mockReturnValue(false),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const context = {
+            pages: vi.fn().mockReturnValue([leftover]),
+            newPage: vi.fn().mockResolvedValue(created),
+            cookies: vi.fn().mockResolvedValue([]),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(context),
+        });
+        const lease = await manager.getPage({ profileId: 'default', session: 'site:district', surface: 'adapter', siteSession: 'persistent', freshPage: true });
+        expect(lease.page).toBe(created);
+        expect(context.newPage).toHaveBeenCalled();
+    });
     it('closes ephemeral adapter sessions when released', async () => {
         const launched = fakeContext();
         const manager = new CloakSessionManager({
@@ -89,4 +152,86 @@ describe('CloakSessionManager', () => {
         expect(lease.page.close).not.toHaveBeenCalled();
         expect(await manager.listPages({ profileId: 'default' })).toHaveLength(1);
     });
+    it('launches a preferred profile when no Cloak profile is active', async () => {
+        const launched = fakeContext();
+        const launchPersistentContext = vi.fn().mockResolvedValue(launched.context);
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext,
+        });
+        await dispatchCloakAction(manager, {
+            id: 'cmd-preferred',
+            action: 'navigate',
+            session: 'work',
+            surface: 'browser',
+            url: 'https://example.com/',
+            preferredContextId: 'profile-default',
+        });
+        expect(launchPersistentContext).toHaveBeenCalledTimes(1);
+        expect(launchPersistentContext.mock.calls[0][0].userDataDir).toBe(expectedProfileDir('profile-default'));
+    });
+    it('falls back to the only active profile when the preferred profile is stale', async () => {
+        const launched = fakeContext();
+        const launchPersistentContext = vi.fn().mockResolvedValue(launched.context);
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext,
+        });
+        await dispatchCloakAction(manager, {
+            id: 'cmd-active',
+            action: 'navigate',
+            session: 'work',
+            surface: 'browser',
+            url: 'https://example.com/',
+            contextId: 'active',
+        });
+        await dispatchCloakAction(manager, {
+            id: 'cmd-stale-default',
+            action: 'navigate',
+            session: 'work',
+            surface: 'browser',
+            url: 'https://example.com/next',
+            preferredContextId: 'stale-default',
+        });
+        expect(launchPersistentContext).toHaveBeenCalledTimes(1);
+        expect(launchPersistentContext.mock.calls[0][0].userDataDir).toBe(expectedProfileDir('active'));
+    });
+    it('asks for an explicit profile when a stale preferred profile meets multiple active profiles', async () => {
+        const launched = fakeContext();
+        const launchPersistentContext = vi.fn().mockResolvedValue(launched.context);
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext,
+        });
+        await dispatchCloakAction(manager, {
+            id: 'cmd-a',
+            action: 'navigate',
+            session: 'work-a',
+            surface: 'browser',
+            url: 'https://example.com/a',
+            contextId: 'profile-a',
+        });
+        await dispatchCloakAction(manager, {
+            id: 'cmd-b',
+            action: 'navigate',
+            session: 'work-b',
+            surface: 'browser',
+            url: 'https://example.com/b',
+            contextId: 'profile-b',
+        });
+        const result = await dispatchCloakAction(manager, {
+            id: 'cmd-stale',
+            action: 'navigate',
+            session: 'work',
+            surface: 'browser',
+            url: 'https://example.com/',
+            preferredContextId: 'stale-default',
+        });
+        expect(result).toMatchObject({
+            id: 'cmd-stale',
+            ok: false,
+            errorCode: 'profile_required',
+        });
+        expect(launchPersistentContext).toHaveBeenCalledTimes(2);
+    });
 });

package/dist/src/build-manifest.js

@@ -103,6 +103,7 @@ function toManifestEntry(cmd, modulePath, sourceFile) {
         sourceFile,
         navigateBefore: cmd.navigateBefore,
         siteSession: cmd.siteSession,
+        freshPage: cmd.freshPage,
         defaultWindowMode: cmd.defaultWindowMode,
     };
 }

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

@@ -81,6 +81,40 @@ describe('manifest helper rules', () => {
         expect(entries[0].sourceFile).not.toContain('\\');
         getRegistry().delete(key);
     });
+    it('serializes freshPage for persistent browser commands', async () => {
+        const site = `manifest-fresh-page-${Date.now()}`;
+        const key = `${site}/checkout`;
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-manifest-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, `${site}.ts`);
+        fs.writeFileSync(file, `export const command = cli({ site: '${site}', name: 'checkout', access: 'write' });`);
+        const entries = await loadManifestEntries(file, site, async () => ({
+            command: cli({
+                site,
+                name: 'checkout',
+                access: 'write',
+                description: 'checkout command',
+                strategy: Strategy.COOKIE,
+                browser: true,
+                siteSession: 'persistent',
+                freshPage: true,
+            }),
+        }));
+        expect(entries).toMatchObject([
+            {
+                site,
+                name: 'checkout',
+                access: 'write',
+                strategy: 'cookie',
+                browser: true,
+                siteSession: 'persistent',
+                freshPage: true,
+                type: 'js',
+                modulePath: `${site}/${site}.js`,
+            },
+        ]);
+        getRegistry().delete(key);
+    });
     it('falls back to registry delta for side-effect-only cli modules', async () => {
         const site = `manifest-side-effect-${Date.now()}`;
         const key = `${site}/legacy`;

package/dist/src/cli.js

@@ -7,6 +7,7 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import * as readline from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
 import { Command, InvalidArgumentError, Option } from 'commander';
 import { findPackageRoot, getBuiltEntryCandidates } from './package-paths.js';
@@ -16,10 +17,10 @@ import { render as renderOutput } from './output.js';
 import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled, formatExternalCliLabel } from './external.js';
-import { listWebcmdSkills, readWebcmdSkill } from './skills.js';
+import { installWebcmdSkill, listWebcmdSkills, updateWebcmdSkill } from './skills.js';
 import { registerAllCommands } from './commanderAdapter.js';
 import { classifyAdapter, formatRootAdapterHelpText, installCommanderNamespaceStructuredHelp, installStructuredHelp, leadingPositionalFromUsage, rootHelpData } from './help.js';
-import { EXIT_CODES, getErrorMessage, BrowserConnectError, CliError } from './errors.js';
+import { EXIT_CODES, getErrorMessage, BrowserConnectError, CliError, ArgumentError } from './errors.js';
 import { TargetError } from './browser/target-errors.js';
 import { resolveTargetJs, getTextResolvedJs, getValueResolvedJs, getAttributesResolvedJs, selectResolvedJs, isAutocompleteResolvedJs } from './browser/target-resolver.js';
 import { buildFindJs, buildSemanticFindJs, isFindError } from './browser/find.js';
@@ -36,7 +37,7 @@ import { daemonRestart, daemonStatus, daemonStop } from './commands/daemon.js';
 import { log } from './logger.js';
 import { bindTab, BrowserCommandError, sendCommand } from './browser/daemon-client.js';
 import { fetchDaemonStatus } from './browser/daemon-transport.js';
-import { aliasForContextId, loadProfileConfig, renameProfile, resolveProfileContextId, setDefaultProfile } from './browser/profile.js';
+import { aliasForContextId, loadProfileConfig, profileRouteParams, renameProfile, resolveProfileSelection, setDefaultProfile } from './browser/profile.js';
 import { formatDaemonVersion, isDaemonStale } from './browser/daemon-version.js';
 import { DEFAULT_BROWSER_CONNECT_TIMEOUT } from './browser/config.js';
 import { CLI_COMMAND } from './brand.js';
@@ -58,6 +59,70 @@ function parseDurationMs(raw, flagName) {
 function timestampFromRaw(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : Date.now();
 }
+function isInteractiveInstall(opts) {
+    return !opts.json && process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+async function resolveSkillInstallOptions(opts) {
+    if (!isInteractiveInstall(opts))
+        return opts;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const scope = opts.scope ?? await choosePrompt(rl, 'Where should Webcmd install skills?', [
+            { key: '1', label: 'Global', value: 'user', aliases: ['global', 'user', 'g'] },
+            { key: '2', label: 'Local project', value: 'project', aliases: ['local', 'project', 'l'] },
+        ], '1');
+        const provider = opts.provider ?? (opts.path ? undefined : await choosePrompt(rl, 'Which coding agent should use them?', [
+            { key: '1', label: 'Agents', value: 'agents', aliases: ['agents', 'agent', 'a'] },
+            { key: '2', label: 'Codex', value: 'codex', aliases: ['codex', 'c'] },
+            { key: '3', label: 'Claude', value: 'claude', aliases: ['claude', 'claude-code'] },
+            { key: '4', label: 'Custom path', value: 'custom', aliases: ['custom', 'path'] },
+        ], '1'));
+        const customPath = opts.path ?? (provider === 'custom' ? await nonEmptyPrompt(rl, 'Skills directory path: ') : undefined);
+        return { ...opts, scope, provider: provider === 'custom' ? undefined : provider, path: customPath };
+    }
+    finally {
+        rl.close();
+    }
+}
+async function choosePrompt(rl, question, choices, defaultKey) {
+    console.log(question);
+    for (const choice of choices)
+        console.log(`  ${choice.key}) ${choice.label}`);
+    while (true) {
+        const answer = (await rl.question(`Choose [${defaultKey}]: `)).trim().toLowerCase() || defaultKey;
+        const choice = choices.find((item) => item.key === answer || item.aliases.includes(answer));
+        if (choice)
+            return choice.value;
+        console.log(`Choose one of: ${choices.map((item) => item.key).join(', ')}`);
+    }
+}
+async function nonEmptyPrompt(rl, question) {
+    while (true) {
+        const answer = (await rl.question(question)).trim();
+        if (answer)
+            return answer;
+        console.log('Path is required.');
+    }
+}
+async function handleSkillLinkCommand(action, json, verb) {
+    try {
+        const result = await action();
+        if (json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Webcmd skills ${verb}: ${result.skills.length}`);
+        for (const skill of result.skills) {
+            console.log(`${skill.name}: ${skill.destination ? `${skill.destination} -> ` : ''}${skill.stableLink}`);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${getErrorMessage(err)}`);
+        if (err instanceof CliError && err.hint)
+            console.error(`Hint: ${err.hint}`);
+        process.exitCode = err instanceof CliError ? err.exitCode : EXIT_CODES.GENERIC_ERROR;
+    }
+}
 function toIsoTimestamp(timestamp) {
     if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp <= 0)
         return undefined;
@@ -428,7 +493,7 @@ async function resolveStoredBrowserTarget(page, scope) {
     return resolveBrowserTargetInSession(page, defaultPage, { scope, source: 'saved' });
 }
 /** Create a browser page for browser commands. Uses a named browser session for continuity. */
-async function getBrowserPage(session, targetPage, contextId, opts = {}) {
+async function getBrowserPage(session, targetPage, profileSelection, opts = {}) {
     const { BrowserBridge } = await import('./browser/index.js');
     const bridge = new BrowserBridge();
     // Internal GC timeout for browser sessions. Not the per-command runtime timeout.
@@ -438,11 +503,11 @@ async function getBrowserPage(session, targetPage, contextId, opts = {}) {
         timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT,
         session,
         surface: 'browser',
-        ...(contextId && { contextId }),
+        ...profileRouteParams(profileSelection),
         ...(idleTimeout && idleTimeout > 0 && { idleTimeout }),
         windowMode: opts.windowMode ?? getBrowserWindowMode(undefined, 'foreground'),
     });
-    const targetScope = getBrowserScope(session, contextId);
+    const targetScope = getBrowserScope(session, profileSelection?.contextId);
     const resolvedTargetPage = targetPage
         ? await resolveBrowserTargetInSession(page, targetPage, { scope: targetScope, source: 'explicit' })
         : await resolveStoredBrowserTarget(page, targetScope);
@@ -497,9 +562,9 @@ function getBrowserSession(command) {
         return raw.trim();
     throw new Error('<session> is a required positional argument: webcmd browser <session> <command>');
 }
-function getBrowserContextId(command) {
+function getBrowserProfileSelection(command) {
     const raw = getCommandOption(command, 'profile');
-    return resolveProfileContextId(typeof raw === 'string' && raw.trim() ? raw.trim() : undefined);
+    return resolveProfileSelection(typeof raw === 'string' && raw.trim() ? raw.trim() : undefined);
 }
 function getPageSession(page) {
     const session = page.session;
@@ -508,8 +573,11 @@ function getPageSession(page) {
     throw new Error('Browser page is missing a session');
 }
 function getPageScope(page) {
-    const contextId = page.contextId;
-    return getBrowserScope(getPageSession(page), typeof contextId === 'string' && contextId.trim() ? contextId.trim() : undefined);
+    const { contextId, preferredContextId } = page;
+    const selected = typeof contextId === 'string' && contextId.trim()
+        ? contextId.trim()
+        : (typeof preferredContextId === 'string' && preferredContextId.trim() ? preferredContextId.trim() : undefined);
+    return getBrowserScope(getPageSession(page), selected);
 }
 function snapshotMetricText(snapshot) {
     return typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2);
@@ -708,10 +776,20 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     });
     const skillsCmd = program
         .command('skills')
-        .description('Read bundled Webcmd skills');
+        .description('List, install, and update bundled Webcmd skills')
+        .action(() => {
+        const rows = listWebcmdSkills();
+        renderOutput(rows, {
+            fmt: 'table',
+            fmtExplicit: false,
+            columns: ['name', 'description', 'version', 'path'],
+            title: 'webcmd/skills/list',
+            source: 'webcmd skills',
+        });
+    });
     skillsCmd
         .command('list')
-        .description('List bundled webcmd-* skills')
+        .description('List bundled Webcmd skills')
         .option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table')
         .action((opts) => {
         const rows = listWebcmdSkills();
@@ -724,30 +802,38 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         });
     });
     skillsCmd
-        .command('read')
-        .description("Print a bundled webcmd-* skill's SKILL.md or reference file")
-        .argument('<skill>', 'Skill name, or skill/path like webcmd-browser/references/foo.md')
-        .argument('[path]', 'Path under the skill directory')
-        .option('--json', 'Output a JSON envelope instead of raw markdown', false)
-        .action((skill, skillPath, opts) => {
-        let result;
-        try {
-            result = readWebcmdSkill(skill, skillPath ?? '');
-        }
-        catch (err) {
-            console.error(`Error: ${getErrorMessage(err)}`);
-            if (err instanceof CliError && err.hint)
-                console.error(`Hint: ${err.hint}`);
-            process.exitCode = err instanceof CliError ? err.exitCode : EXIT_CODES.GENERIC_ERROR;
-            return;
-        }
-        if (opts.json) {
-            console.log(JSON.stringify(result, null, 2));
-            return;
-        }
-        process.stdout.write(result.content);
-        if (!result.content.endsWith('\n'))
-            process.stdout.write('\n');
+        .command('install')
+        .description('Install bundled Webcmd skills into an agent skills folder')
+        .option('-p, --provider <provider>', 'Agent provider: agents, codex, claude')
+        .option('-s, --scope <scope>', 'Install scope: user/global or project/local')
+        .option('--path <path>', 'Custom agent skills directory')
+        .option('--json', 'Output a JSON envelope', false)
+        .action(async (opts) => {
+        await handleSkillLinkCommand(async () => {
+            const resolved = await resolveSkillInstallOptions(opts);
+            if (resolved.provider === 'custom' && !resolved.path) {
+                throw new ArgumentError('Custom skill provider requires --path.', 'Pass --path <skills-dir> or run interactively.');
+            }
+            return installWebcmdSkill({
+                provider: resolved.provider,
+                scope: resolved.scope,
+                customPath: resolved.path,
+            });
+        }, opts.json, 'installed');
+    });
+    skillsCmd
+        .command('update')
+        .description('Refresh bundled Webcmd skill symlinks after updating the package')
+        .option('-p, --provider <provider>', 'Also repair provider link: agents, codex, claude')
+        .option('-s, --scope <scope>', 'Also repair scoped link: user/global or project/local')
+        .option('--path <path>', 'Also repair a custom agent skills directory')
+        .option('--json', 'Output a JSON envelope', false)
+        .action(async (opts) => {
+        await handleSkillLinkCommand(() => updateWebcmdSkill({
+            provider: opts.provider,
+            scope: opts.scope,
+            customPath: opts.path,
+        }), opts.json, 'updated');
     });
     const authCmd = registerAuthCommands(program);
     program
@@ -882,9 +968,9 @@ Examples:
                 const command = args.at(-1) instanceof Command ? args.at(-1) : undefined;
                 const targetPage = getBrowserTargetId(command);
                 const session = getBrowserSession(command);
-                const contextId = getBrowserContextId(command);
+                const profileSelection = getBrowserProfileSelection(command);
                 const windowMode = getBrowserWindowMode(command, 'foreground');
-                page = await getBrowserPage(session, targetPage, contextId, { windowMode });
+                page = await getBrowserPage(session, targetPage, profileSelection, { windowMode });
                 await fn(page, ...args);
             }
             catch (err) {
@@ -933,12 +1019,14 @@ Examples:
                 ? optsOrCommand
                 : {};
             const session = getBrowserSession(command);
-            const contextId = getBrowserContextId(command);
+            const profileSelection = getBrowserProfileSelection(command);
+            const contextId = profileSelection?.contextId;
+            const routing = profileRouteParams(profileSelection);
             try {
                 const { BrowserBridge } = await import('./browser/index.js');
                 const bridge = new BrowserBridge();
-                await bridge.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT, session, surface: 'browser', ...(contextId && { contextId }) });
-                await fn({ session, contextId }, opts);
+                await bridge.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT, session, surface: 'browser', ...routing });
+                await fn({ session, contextId, routing }, opts);
             }
             catch (err) {
                 if (err instanceof BrowserCommandError) {
@@ -956,7 +1044,7 @@ Examples:
         .description('Bind an existing Cloak runtime tab to the browser session named by <session>')
         .option('--page <id>', 'Cloak tab page id from `webcmd browser <session> tab list`')
         .option('--index <n>', 'Cloak tab index from `webcmd browser <session> tab list`')
-        .action(browserSessionCommandAction(async ({ session, contextId }, opts) => {
+        .action(browserSessionCommandAction(async ({ session, contextId, routing }, opts) => {
         const page = typeof opts.page === 'string' && opts.page.trim() ? opts.page.trim() : undefined;
         const rawIndex = typeof opts.index === 'string' && opts.index.trim() ? opts.index.trim() : undefined;
         if ((page && rawIndex) || (!page && !rawIndex)) {
@@ -966,14 +1054,14 @@ Examples:
             throw new BrowserCommandError('--index must be a non-negative integer.', 'invalid_request');
         }
         const index = rawIndex === undefined ? undefined : Number.parseInt(rawIndex, 10);
-        const data = await bindTab(session, { ...(contextId && { contextId }), ...(page && { page }), ...(index !== undefined && { index }) });
+        const data = await bindTab(session, { ...routing, ...(page && { page }), ...(index !== undefined && { index }) });
         saveBrowserTargetState(undefined, getBrowserScope(session, contextId));
         console.log(JSON.stringify({ session, ...((data && typeof data === 'object') ? data : { data }) }, null, 2));
     }));
     browser.command('unbind')
         .description('Compatibility command; release the Cloak browser session named by <session>')
-        .action(browserSessionCommandAction(async ({ session, contextId }) => {
-        await sendCommand('close-window', { session, surface: 'browser', ...(contextId && { contextId }) });
+        .action(browserSessionCommandAction(async ({ session, contextId, routing }) => {
+        await sendCommand('close-window', { session, surface: 'browser', ...routing });
         saveBrowserTargetState(undefined, getBrowserScope(session, contextId));
         console.log(JSON.stringify({ unbound: true, session }, null, 2));
     }));

package/dist/src/cli.test.js

@@ -1004,7 +1004,7 @@ describe('profile list', () => {
                 runtimeVersion: '1.0.3',
                 pending: 0,
                 memoryMB: 20,
-                port: 19825,
+                port: 9777,
             }),
         });
         const program = createProgram('', '');
@@ -1027,7 +1027,7 @@ describe('profile list', () => {
                 profiles: [],
                 pending: 0,
                 memoryMB: 20,
-                port: 19825,
+                port: 9777,
             }),
         });
         const program = createProgram('', '');

package/dist/src/commands/daemon.test.js

@@ -39,7 +39,7 @@ describe('daemonStatus', () => {
             runtimeVersion: '1.6.8',
             pending: 0,
             memoryMB: 64,
-            port: 19825,
+            port: 9777,
         });
         await daemonStatus();
         expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('running'));
@@ -49,7 +49,7 @@ describe('daemonStatus', () => {
         expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('connected'));
         expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('v1.6.8'));
         expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('64 MB'));
-        expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('19825'));
+        expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('9777'));
     });
     it('shows disconnected when runtime is not connected', async () => {
         fetchDaemonStatusMock.mockResolvedValue({
@@ -61,7 +61,7 @@ describe('daemonStatus', () => {
             runtimeName: 'fake',
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
         });
         await daemonStatus();
         expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('disconnected'));
@@ -77,7 +77,7 @@ describe('daemonStatus', () => {
             runtimeVersion: undefined,
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
         });
         await daemonStatus();
         expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('fake connected'));
@@ -105,7 +105,7 @@ describe('daemonStatus runtime label states (#1575)', () => {
             daemonVersion: PKG_VERSION,
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
             runtimeName: 'fake',
             ...extra,
         });
@@ -173,7 +173,7 @@ describe('daemonStop', () => {
             runtimeName: 'fake',
             pending: 0,
             memoryMB: 50,
-            port: 19825,
+            port: 9777,
         });
         requestDaemonShutdownMock.mockResolvedValue(true);
         await daemonStop();
@@ -190,7 +190,7 @@ describe('daemonStop', () => {
             runtimeName: 'fake',
             pending: 0,
             memoryMB: 50,
-            port: 19825,
+            port: 9777,
         });
         requestDaemonShutdownMock.mockResolvedValue(false);
         await daemonStop();
@@ -221,7 +221,7 @@ describe('daemonRestart', () => {
             profiles: [{ contextId: 'work', runtimeConnected: true, pending: 0 }],
             pending: 0,
             memoryMB: 50,
-            port: 19825,
+            port: 9777,
         });
         restartDaemonMock.mockResolvedValue({
             previousStatus: { daemonVersion: '1.7.6' },
@@ -237,13 +237,13 @@ describe('daemonRestart', () => {
                 profiles: [{ contextId: 'work', runtimeConnected: true, pending: 0 }],
                 pending: 0,
                 memoryMB: 51,
-                port: 19825,
+                port: 9777,
             },
         });
         await daemonRestart();
         expect(restartDaemonMock).toHaveBeenCalledTimes(1);
         expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('will disconnect 1 browser profile'));
-        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining(`Daemon restarted on port 19825 (v${PKG_VERSION})`));
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining(`Daemon restarted on port 9777 (v${PKG_VERSION})`));
         expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('Runtime connected; 1 profile connected'));
     });
     it('starts a new daemon when none was running', async () => {
@@ -261,11 +261,11 @@ describe('daemonRestart', () => {
                 runtimeName: 'fake',
                 pending: 0,
                 memoryMB: 51,
-                port: 19825,
+                port: 9777,
             },
         });
         await daemonRestart();
-        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining(`Daemon started on port 19825 (v${PKG_VERSION})`));
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining(`Daemon started on port 9777 (v${PKG_VERSION})`));
         expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('Cloak runtime has not connected yet'));
     });
     it('reports failure when the daemon cannot stop', async () => {
@@ -278,7 +278,7 @@ describe('daemonRestart', () => {
             runtimeName: 'fake',
             pending: 0,
             memoryMB: 50,
-            port: 19825,
+            port: 9777,
         });
         restartDaemonMock.mockResolvedValue({
             previousStatus: { daemonVersion: '1.7.6' },

package/dist/src/constants.d.ts

@@ -2,9 +2,8 @@
  * Shared constants used across explore, synthesize, and pipeline modules.
  */
 import { DAEMON_HEADER_NAME } from './brand.js';
-/** Default daemon port for HTTP/WebSocket communication with browser extension */
-export declare const DEFAULT_DAEMON_PORT = 19825;
-export declare function unsupportedDaemonPortEnvMessage(value?: string): string;
+/** Default daemon port for HTTP communication with the browser runtime. */
+export declare const DEFAULT_DAEMON_PORT = 9777;
 export { DAEMON_HEADER_NAME };
 /** URL query params that are volatile/ephemeral and should be stripped from patterns */
 export declare const VOLATILE_PARAMS: Set<string>;