@genspark/cli 1.4.2 → 1.5.1

package/dist/index.js

@@ -26,13 +26,15 @@ import * as os from 'os';
 import * as pathModule from 'path';
 import { createRequire } from 'module';
 import { spawn } from 'child_process';
-import { ApiClient, unauthenticatedRequest } from './client.js';
-import { setDebugEnabled, setOutputFormat, debug, info, error as logError, output, } from './logger.js';
-import { loadConfigFile, saveConfigFile, getConfigPath, loadToolsCache, saveToolsCache, setConfigPathOverride, } from './config.js';
+import { ApiClient, isAuthError, unauthenticatedRequest, } from './client.js';
+import { classifyFileArg, awaitLocalFileReady, decideAfterWait, localFileNotReadyError, } from './localFiles.js';
+import { setDebugEnabled, setOutputFormat, debug, info, warn, error as logError, output, } from './logger.js';
+import { loadConfigFile, getConfigPath, loadToolsCache, normalizeBaseUrl, saveToolsCache, setConfigPathOverride, updateConfigFile, } from './config.js';
 import { checkForUpdates } from './updater.js';
+import { getSandboxRuntime } from './runtime.js';
 import { registerDesignCommand } from './commands/design.js';
 import { pickExistingFileOperand } from './commands/aidrive-upload.js';
-import { parseLastSeenIndex, eventStdoutLine, } from './commands/chat-events.js';
+import { parseLastSeenIndex, eventStdoutLine } from './commands/chat-events.js';
 import { mediaItemsKeyFor, mediaSummaryLines } from './mediaSummary.js';
 import { registerMeshCommand, getMeshInvocation, runMesh, } from './commands/mesh.js';
 import { executeCloneUrl, normalizeCloneUrlForGit, } from './commands/sb-git-clone.js';
@@ -104,9 +106,13 @@ function getGlobalOptions() {
     // API key priority: CLI > env > config file
     const apiKey = opts.apiKey || process.env.GSK_API_KEY || fileConfig.api_key;
     // Base URL priority: CLI > env > config file > default
-    const baseUrl = opts.baseUrl !== DEFAULT_BASE_URL
+    const explicitBaseUrl = program.getOptionValueSource('baseUrl') === 'cli'
         ? opts.baseUrl
-        : process.env.GSK_BASE_URL || fileConfig.base_url || DEFAULT_BASE_URL;
+        : undefined;
+    const baseUrl = normalizeBaseUrl(explicitBaseUrl ||
+        process.env.GSK_BASE_URL ||
+        fileConfig.base_url ||
+        DEFAULT_BASE_URL);
     // Timeout priority: CLI > config file > default
     const timeout = opts.timeout !== String(DEFAULT_TIMEOUT)
         ? parseInt(opts.timeout, 10)
@@ -151,6 +157,7 @@ const CONTENT_TYPE_MAP = {
     '.png': 'image/png',
     '.gif': 'image/gif',
     '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
     '.pdf': 'application/pdf',
     '.txt': 'text/plain',
     '.json': 'application/json',
@@ -158,6 +165,20 @@ const CONTENT_TYPE_MAP = {
     '.css': 'text/css',
     '.js': 'application/javascript',
     '.ts': 'application/typescript',
+    '.jsx': 'text/javascript',
+    '.tsx': 'text/typescript',
+    '.vue': 'text/html',
+    '.py': 'text/x-python',
+    '.java': 'text/x-java-source',
+    '.go': 'text/x-go',
+    '.rs': 'text/x-rust',
+    '.c': 'text/x-c',
+    '.cc': 'text/x-c++',
+    '.cpp': 'text/x-c++',
+    '.h': 'text/x-c',
+    '.hpp': 'text/x-c++',
+    '.yaml': 'application/x-yaml',
+    '.yml': 'application/x-yaml',
     '.md': 'text/markdown',
     '.xml': 'application/xml',
     '.csv': 'text/csv',
@@ -167,6 +188,46 @@ const CONTENT_TYPE_MAP = {
     '.wav': 'audio/wav',
     '.webm': 'video/webm',
 };
+/** Preserve interleaved --image/--file order; Commander groups options by key. */
+export function collectDesignAttachmentArgs(argv) {
+    const result = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        const equalsMatch = token.match(/^--(image|file)=(.+)$/);
+        if (equalsMatch) {
+            result.push({
+                path: equalsMatch[2],
+                role: equalsMatch[1] === 'image' ? 'visual_reference' : 'context',
+            });
+            continue;
+        }
+        if (token !== '--image' && token !== '--file')
+            continue;
+        const role = token === '--image' ? 'visual_reference' : 'context';
+        while (index + 1 < argv.length && !argv[index + 1].startsWith('-')) {
+            result.push({ path: argv[index + 1], role });
+            index += 1;
+        }
+    }
+    return result;
+}
+async function uploadDesignAttachments(values, client) {
+    const attachments = [];
+    // Upload the complete batch before executeTool: any failure aborts project
+    // creation/continuation rather than leaving a half-bound Design project.
+    for (const value of values) {
+        const localPath = expandHome(value.path);
+        if (!isLocalFilePath(localPath)) {
+            throw new Error(`File not found: ${value.path}`);
+        }
+        const name = pathModule.basename(localPath);
+        const ext = pathModule.extname(localPath).toLowerCase();
+        const mimeType = CONTENT_TYPE_MAP[ext] || 'application/octet-stream';
+        const url = await uploadLocalFile(localPath, client);
+        attachments.push({ url, name, mime_type: mimeType, role: value.role });
+    }
+    return attachments;
+}
 /**
  * Stream a local file to a URL using Node.js http/https.request +
  * fs.createReadStream so the file is never fully buffered in memory.
@@ -338,9 +399,27 @@ function isLocalFilePath(value) {
         fs.existsSync(value));
 }
 async function resolveFileArg(value, client) {
-    if (!isLocalFilePath(value))
+    // Classify the RAW value: a leading '~' is positive local evidence and must
+    // hit classifyFileArg's relative-marker branch before any expansion.
+    const kind = classifyFileArg(value);
+    if (kind === 'remote' || kind === 'aidrive')
         return value;
-    return await uploadLocalFile(value, client);
+    // fs never expands '~' — expand only for the filesystem operations below.
+    const localPath = expandHome(value);
+    // Tolerate the same-batch create-then-read race (a parallel sibling tool
+    // call may still be writing the file) before deciding what the arg is.
+    const readiness = await awaitLocalFileReady(localPath);
+    switch (decideAfterWait(kind, readiness)) {
+        case 'upload':
+            return await uploadLocalFile(localPath, client);
+        case 'error':
+            throw new Error(localFileNotReadyError(localPath, readiness));
+        case 'passthrough':
+            // No local evidence beyond the parent directory: let the backend try
+            // it as an AI Drive path (its failure mode is a per-URL actionable
+            // error, not a generic one).
+            return value;
+    }
 }
 /**
  * Inline-base64 transport limit for email `attachments`. Anything larger
@@ -547,7 +626,9 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
         const prefix = groupName + '_';
         cmdName =
             tool.cli.subcommand ||
-                (tool.name.startsWith(prefix) ? tool.name.slice(prefix.length) : tool.name);
+                (tool.name.startsWith(prefix)
+                    ? tool.name.slice(prefix.length)
+                    : tool.name);
     }
     const cmd = targetProgram
         .command(cmdName, cmdOpts?.hidden ? { hidden: true } : {})
@@ -560,6 +641,12 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
     }
     const props = tool.parameters?.properties || {};
     const required = tool.parameters?.required || [];
+    // When --args-file is on the command line, required params may live in
+    // the file, which Commander cannot see — its parse-time required checks
+    // would reject the invocation before the file is ever read. Register
+    // everything optional in that case; the action handler re-validates the
+    // required set AFTER the file merge (#46011).
+    const argsFileInvoked = process.argv.some(a => a === '--args-file' || a.startsWith('--args-file='));
     // If primary_arg is set, make it a positional argument
     if (tool.cli.primary_arg && props[tool.cli.primary_arg]) {
         const param = props[tool.cli.primary_arg];
@@ -573,7 +660,9 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
         // usage say e.g. "missing required argument 'deck'" instead of 'value'
         // (#43556: the anonymous form sent agents guessing).
         const argName = tool.cli.primary_arg;
-        const bracket = isRequired && !isServiceAction ? `<${argName}>` : `[${argName}]`;
+        const bracket = isRequired && !isServiceAction && !argsFileInvoked
+            ? `<${argName}>`
+            : `[${argName}]`;
         cmd.argument(bracket, param.description || argName);
     }
     // Add remaining params as --options
@@ -588,7 +677,8 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
         // requiredOption would block every invocation before the action handler
         // (and its collector) ever runs.
         const isRequired = tool.name === 'create_task' ||
-            (tool.name === 'skills_save' && name === 'files')
+            (tool.name === 'skills_save' && name === 'files') ||
+            argsFileInvoked
             ? false
             : required.includes(name);
         const paramType = Array.isArray(param.type) ? param.type[0] : param.type;
@@ -651,6 +741,14 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
         cmd.option('--attach <values...>', 'Attach local files or URLs (alias for --attachments; repeatable)');
         cmd.option('--attachment <values...>', 'Attach local files or URLs (alias for --attachments; repeatable)');
     }
+    // Quoting-hazard-free input path (#46011): a shell-invoked agent passing
+    // rich text in double quotes gets `$`-tokens expanded before gsk sees
+    // argv ("$150k" → "50k"). A JSON file / stdin never crosses shell quoting.
+    cmd.option('--args-file <path>', 'Read arguments from a JSON object file ("-" = stdin). File keys ' +
+        'override flag values. Use for rich text (strings containing $, ' +
+        'quotes, newlines) instead of double-quoted flags. Server ' +
+        'parameters only — CLI-only options (e.g. --local_file) must ' +
+        'still be passed as flags.');
     // Add -o/--output-file option for tools that produce downloadable files
     const outputFileKeys = tool.cli.output_file_keys || [];
     if (outputFileKeys.length > 0) {
@@ -661,7 +759,8 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
         cmd.option('--acp', 'Start as ACP (Agent Client Protocol) stdio agent instead of one-shot execution', false);
         cmd.option('-o, --output-file <path>', 'Export the artifact (pptx/docx/xlsx) to a local file after task completes');
         cmd.option('--session-id <id>', 'ACP session ID (used with get-project)');
-        cmd.option('--file <values...>', 'Import local CSV/Excel files into the task (auto-uploaded to blob storage)');
+        cmd.option('--file <values...>', 'Import local files (Design: structured context; other tasks: CSV/Excel file_urls)');
+        cmd.option('--image <values...>', 'Design only: upload ordered local visual references');
         cmd.addHelpText('after', '\nVirtual subcommands:\n' +
             '  get-project              Get Genspark project info for an ACP session (local file lookup, no API call)\n' +
             '    --session-id <id>      ACP session ID (required)\n' +
@@ -669,6 +768,10 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             'Example:\n' +
             '  gsk task get-project --session-id <acp_session_id>\n');
     }
+    if (tool.name === 'task_continue') {
+        cmd.option('--image <values...>', 'Design only: append ordered local visual references');
+        cmd.option('--file <values...>', 'Design only: append ordered local context files');
+    }
     // For the aidrive tool, add client-side options used with --local_file upload
     if (tool.name === 'aidrive') {
         cmd.option('--local_file <path>', 'Local file path to upload to AI Drive (supports files >5 MB; alternative to --file_content)');
@@ -718,7 +821,10 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             : undefined;
         if (tool.cli.primary_arg === 'action' &&
             Array.isArray(actionEnum) &&
-            primaryArgValue === undefined) {
+            primaryArgValue === undefined &&
+            // The action may arrive via --args-file (read later in the
+            // handler) — don't short-circuit to the action listing then.
+            !opts.argsFile) {
             logError(tool.description);
             logError(`Available actions: ${actionEnum.join(', ')}`);
             logError(`Usage: gsk ${cmd.name()} <action> [options]  ` +
@@ -764,8 +870,10 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
                 await startAcpBridge(taskType, clientFactory().getOptions());
                 return;
             }
-            // For create_task (non-ACP): validate required params manually
-            if (tool.name === 'create_task') {
+            // For create_task (non-ACP): validate required params manually.
+            // Skipped when --args-file is present — required params may live in
+            // the file, and the post-merge revalidation below enforces them.
+            if (tool.name === 'create_task' && !opts.argsFile) {
                 for (const reqParam of required) {
                     if (reqParam === tool.cli.primary_arg)
                         continue;
@@ -801,6 +909,19 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             delete opts.outputFile;
             delete opts.acp; // ACP flag is client-side only
             delete opts.sessionId; // get-project flag is client-side only
+            const argsFilePath = opts.argsFile;
+            delete opts.argsFile; // client-side only; merged below
+            // Required checks were relaxed because --args-file appeared in argv;
+            // an explicitly EMPTY value (`--args-file=` / `--args-file ""`,
+            // parsed as '') would skip the merge AND the revalidation below — a
+            // validation bypass, not a degenerate no-op. Refuse it. undefined is
+            // deliberately allowed: argv detection can false-positive on a
+            // literal "--args-file" VALUE of another option, and the server-side
+            // required validation still covers that arm.
+            if (argsFilePath !== undefined && !argsFilePath) {
+                logError('--args-file requires a non-empty path (or "-" for stdin)');
+                process.exit(1);
+            }
             const args = { ...opts };
             // Set primary arg
             if (tool.cli.primary_arg && primaryArgValue !== undefined) {
@@ -831,6 +952,54 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
                 delete args.attach;
                 delete args.attachment;
             }
+            // Merge --args-file after every flag-derived write (positional,
+            // attachment aliases) so file keys genuinely win: the file is the
+            // deliberate rich payload, flags are the convenience layer (#46011).
+            // It sits before the numeric coercion below so file-provided
+            // numeric strings get the same schema-driven coercion flags do.
+            if (argsFilePath) {
+                let fileArgs;
+                try {
+                    const { readArgsFile } = await import('./argsFile.js');
+                    fileArgs = readArgsFile(argsFilePath);
+                }
+                catch (err) {
+                    logError(err.message);
+                    process.exit(1);
+                }
+                // The file carries SERVER parameters only. CLI-only options
+                // (--local_file, --file, --out, ...) are processed from flags by
+                // client-side blocks below that never see the file — honoring
+                // them here would silently do nothing, so warn and drop instead.
+                for (const key of Object.keys(fileArgs)) {
+                    if (!(key in props)) {
+                        warn(`--args-file: "${key}" is not a server parameter of ` +
+                            `${tool.name} and was ignored — CLI-only options must be ` +
+                            'passed as flags.');
+                        delete fileArgs[key];
+                    }
+                }
+                Object.assign(args, fileArgs);
+                // Required params were registered optional because the file may
+                // carry them (Commander validates before the file is readable) —
+                // re-validate the merged set now. CLI-populated params are
+                // exempt: skills_save's `files` is schema-required but filled by
+                // the directory collector further down, which deliberately owns
+                // the value (file-wins does not apply to collector-owned params).
+                for (const reqParam of required) {
+                    if (tool.name === 'skills_save' && reqParam === 'files')
+                        continue;
+                    if (args[reqParam] === undefined || args[reqParam] === null) {
+                        // The primary arg is a positional — there is no --<name>
+                        // flag for it, so the recovery hint must not invent one.
+                        const hint = reqParam === tool.cli.primary_arg
+                            ? `pass it as the positional argument or include it in --args-file`
+                            : `pass --${reqParam} or include it in --args-file`;
+                        logError(`Missing required parameter: ${reqParam} (${hint})`);
+                        process.exit(1);
+                    }
+                }
+            }
             // Coerce numeric strings to numbers based on schema
             for (const [name, param] of Object.entries(props)) {
                 if (args[name] !== undefined) {
@@ -915,6 +1084,10 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
                     info(`Warning: ${dir} carries provenance for ${collected.sidecarOwner} — ` +
                         `saving will fork this skill into your own catalog.`);
                 }
+                // Collector-owned: `files` must be {path, content} read from the
+                // local directory, so this assignment intentionally overrides any
+                // --args-file value (the file-wins rule covers flag-shaped params
+                // only, not CLI-populated ones).
                 args.files = collected.files;
             }
             // aidrive upload ergonomics: `gsk aidrive upload <path>` is the natural
@@ -928,10 +1101,21 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             // no usable source, fail with an actionable message that names
             // --local_file rather than the opaque backend error.
             if (tool.name === 'aidrive' &&
-                primaryArgValue === 'upload' &&
+                // args.action, not the positional: the action may arrive via
+                // --args-file (sb-git's clone-url gate uses the same pattern).
+                args.action === 'upload' &&
                 !opts.local_file &&
-                !opts.file_content) {
-                const pathOperand = pickExistingFileOperand(cmd.args.slice(1));
+                // args, not opts: file_content is a server param and may have
+                // arrived via --args-file (merged into args above).
+                !args.file_content) {
+                // Skip the first operand only when it really is the action: with
+                // the action arriving via --args-file, Commander binds a bare
+                // path to the [action] positional slot, so cmd.args[0] is itself
+                // a path candidate.
+                const operandCandidates = primaryArgValue !== undefined && primaryArgValue === args.action
+                    ? cmd.args.slice(1)
+                    : cmd.args;
+                const pathOperand = pickExistingFileOperand(operandCandidates);
                 if (pathOperand) {
                     opts.local_file = pathOperand;
                 }
@@ -947,7 +1131,7 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             // Stream the file directly to AI Drive via the dedicated tool_cli
             // endpoint (POST /api/tool_cli/aidrive/upload) — no blob middleman.
             if (tool.name === 'aidrive' &&
-                primaryArgValue === 'upload' &&
+                args.action === 'upload' &&
                 opts.local_file) {
                 const localFilePath = opts.local_file;
                 const override = !!opts.override;
@@ -967,8 +1151,23 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
                 output(result);
                 return;
             }
-            // create_task --file: upload local files and pass as file_urls
-            if (tool.name === 'create_task' && opts.file) {
+            const designAttachmentArgs = collectDesignAttachmentArgs(process.argv);
+            const isDesignAttachmentCommand = designAttachmentArgs.length > 0 &&
+                ((tool.name === 'create_task' && args.task_type === 'design') ||
+                    tool.name === 'task_continue');
+            if (isDesignAttachmentCommand) {
+                const uploaded = await uploadDesignAttachments(designAttachmentArgs, client);
+                const existing = Array.isArray(args.attachments)
+                    ? args.attachments
+                    : [];
+                args.attachments = [...existing, ...uploaded];
+                delete args.image;
+                delete args.file;
+            }
+            // Non-Design create_task --file keeps its CSV/Excel file_urls contract.
+            if (tool.name === 'create_task' &&
+                args.task_type !== 'design' &&
+                opts.file) {
                 const fileValues = Array.isArray(opts.file)
                     ? opts.file
                     : [opts.file];
@@ -1153,7 +1352,10 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
                 typeof result.data === 'object') {
                 const data = result.data;
                 const projectId = data.project_id;
-                const taskType = (primaryArgValue || args.type);
+                // args.type is the value actually sent to the API: the positional
+                // is copied into args and --args-file may override it (file wins),
+                // so the export must key on the merged view, never the positional.
+                const taskType = args.type;
                 if (projectId && taskType) {
                     info(`Exporting ${taskType} artifact...`);
                     try {
@@ -1186,8 +1388,7 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             // web_search payloads are large and agent-consumed — indent-2 here
             // is pure token overhead on every SAS/Claw search
             output(result, {
-                compact: tool.name === 'web_search' ||
-                    Boolean(mediaItemsKeyFor(tool.name)),
+                compact: tool.name === 'web_search' || Boolean(mediaItemsKeyFor(tool.name)),
             });
         }
         catch (err) {
@@ -1364,10 +1565,10 @@ program
             const remainingSec = expires_in - elapsedSec;
             const tokenResp = await unauthenticatedRequest(baseUrl, `/api/cli_auth/token?code=${encodeURIComponent(device_code)}`, 'GET');
             if (tokenResp.status === 'approved' && tokenResp.api_key) {
-                // Save to config
-                const config = loadConfigFile();
-                config.api_key = tokenResp.api_key;
-                saveConfigFile(config);
+                updateConfigFile({
+                    api_key: tokenResp.api_key,
+                    base_url: baseUrl,
+                });
                 info('Login successful! API key saved.');
                 output({
                     status: 'ok',
@@ -1405,8 +1606,7 @@ program
             info('Already logged out (no API key in config).');
             return;
         }
-        delete config.api_key;
-        saveConfigFile(config);
+        updateConfigFile({}, ['api_key']);
         info('Logged out. API key removed.');
         output({
             status: 'ok',
@@ -1439,6 +1639,25 @@ program
         process.exit(1);
     }
 });
+// Runtime - report the sandbox environment this CLI process runs in
+program
+    .command('runtime')
+    .description('Show the Genspark sandbox runtime this CLI is running in ' +
+    '(reads the /opt/genspark template marker; all-null outside a sandbox)')
+    .action(() => {
+    const runtime = getSandboxRuntime();
+    output({
+        status: 'ok',
+        message: 'success',
+        data: {
+            family: runtime.family,
+            version: runtime.version,
+            is_sb_box: runtime.isSbBox,
+            is_super_agent_sandbox: runtime.isSuperAgentSandbox,
+            is_genspark_sandbox: runtime.isGensparkSandbox,
+        },
+    });
+});
 // Init OpenCode - generate opencode.json config
 program
     .command('init-opencode')
@@ -1652,6 +1871,13 @@ function _generateContextMd(projectRoot, relSkillsDir, skillDirs) {
 
 Read [gsk-shared](${sharedSkill}) for authentication, global flags, and output conventions.
 
+## Connectors
+
+For any third-party integration (Gmail, Slack, Notion, HubSpot, custom MCP
+servers, ...), start with [gsk-connector](${relSkillsDir}/gsk-connector/SKILL.md) —
+one fixed \`list\` → \`search\` → \`tools <id>\` → \`call <id>\` flow covers every
+connector instead of memorizing per-service commands below.
+
 ## Available Skills
 
 ${skillList}
@@ -1892,12 +2118,16 @@ _groupCommands.set('chat', chatCmd);
 chatCmd
     .command('events <project_id>')
     .description("Attach to the conversation's in-flight run and stream its events " +
-    'live (one JSON line per event on stdout): buffered events since ' +
-    'run start replay first, then live events follow until the run ' +
-    'ends. Prints no_running_agent when the conversation is idle. ' +
-    'After a disconnect, reattach with --last-seen <highest ' +
-    '_event_index already processed> to skip the replayed prefix.')
-    .option('--last-seen <index>', 'resume cursor: only replay events with _event_index greater than this')
+    'live (one JSON line per event on stdout): the first line is a ' +
+    'project_data snapshot event, buffered events since run start ' +
+    'replay next, then live events follow until the run ends. Every ' +
+    'event line carries an _event_index. Prints no_running_agent when ' +
+    'the conversation is idle. Upstream segment ends during long runs ' +
+    'are reattached automatically; after a real disconnect, reattach ' +
+    'with --last-seen <highest _event_index already processed> to ' +
+    'skip the replayed prefix.')
+    .option('--last-seen <index>', 'resume cursor: only replay events with _event_index greater than ' +
+    'this (take it from the last event line of the previous stream)')
     .action(async (projectId, opts) => {
     try {
         const lastSeen = parseLastSeenIndex(opts.lastSeen);
@@ -1921,6 +2151,11 @@ chatCmd
             else if (msg.heartbeat !== undefined) {
                 debug(`  Heartbeat #${msg.heartbeat}`);
             }
+            else if (msg.debug && typeof msg.message === 'string') {
+                // Server-side notices (e.g. transparent segment reattach)
+                // are context, not payload — stderr, --debug only.
+                debug(`  ${msg.message}`);
+            }
         });
         output(result);
         if (result.status === 'error') {
@@ -1944,11 +2179,12 @@ async function main() {
     if (meshArgs !== null) {
         program.parseOptions(process.argv);
         setDebugEnabled(getGlobalOptions().debug);
-        // Forward an explicit `--base-url` flag only (commander leaves it at
-        // DEFAULT_BASE_URL when unset); env/config/prod-default resolution happens
-        // inside the mesh layer so it doesn't inherit gsk's localhost default.
+        // Forward an explicit `--base-url` flag only; env/config/default resolution
+        // happens inside the mesh layer.
         const rawBase = program.opts().baseUrl;
-        const baseUrlOverride = rawBase && rawBase !== DEFAULT_BASE_URL ? rawBase : undefined;
+        const baseUrlOverride = rawBase && program.getOptionValueSource('baseUrl') === 'cli'
+            ? normalizeBaseUrl(rawBase)
+            : undefined;
         await runMesh(meshArgs, baseUrlOverride);
         return;
     }
@@ -1986,7 +2222,20 @@ async function main() {
                 debug(`Fetched and cached ${tools.length} tools from server`);
             }
             catch (err) {
-                debug(`Failed to fetch tools: ${err.message}`);
+                if (isAuthError(err)) {
+                    // A definitive auth verdict must be loud: swallowing it registers
+                    // zero dynamic commands and the user sees "unknown command" with
+                    // no hint that the token is the cause (#45982). Warn-and-continue
+                    // (not fail-fast) so built-in commands — `gsk login` above all —
+                    // still work with an expired token.
+                    warn(`API token rejected (HTTP ${err.httpStatus}) — ` +
+                        'invalid or expired. Server-provided commands were NOT loaded; ' +
+                        'if the command you need is missing, run `gsk login` to ' +
+                        're-authenticate.');
+                }
+                else {
+                    debug(`Failed to fetch tools: ${err.message}`);
+                }
                 // Continue without dynamic commands - built-in commands still work
             }
         }