@openagents-org/agent-launcher 0.2.173 → 0.2.175

package/src/adapters/openclaw.js

@@ -212,6 +212,16 @@ class OpenClawAdapter extends BaseAdapter {
 
   async _handleMessage(msg) {
     let content = (msg.content || '').trim();
+    // Strip a leading mention of OURSELVES. The workspace UI prefixes targeted
+    // messages with "@<agentName>", but OpenClaw's inner agent doesn't know its
+    // workspace name — it sees a message addressed to a stranger and its
+    // group-chat heuristic answers NO_REPLY (empty payloads, silent agent).
+    // Mentions of other participants are left intact.
+    const selfMention = new RegExp(
+      '^\\s*@' + String(this.agentName || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b[,:]?\\s*',
+      'i',
+    );
+    content = content.replace(selfMention, '').trim();
     const attachments = msg.attachments || [];
 
     // Append attachment info
@@ -509,18 +519,34 @@ class OpenClawAdapter extends BaseAdapter {
         const payloads = data.payloads || [];
         this._log(`CLI parsed: ${payloads.length} payloads, keys=${payloads.map(p=>Object.keys(p).join('/')).join(', ')}, text=${payloads.map(p=>(p.text||'').slice(0,50)).join('|')}`);
         if (payloads.length > 0) {
-          const texts = payloads.filter(p => p.text).map(p => p.text);
+          // NO_REPLY is OpenClaw's "deliberately silent" sentinel, not an
+          // answer — surface it as no-response, same as empty payloads.
+          const texts = payloads
+            .filter(p => p.text && String(p.text).trim() !== 'NO_REPLY')
+            .map(p => p.text);
           if (texts.length > 0) {
             resolve(texts.join('\n\n'));
             return;
           }
+          resolve('');
+          return;
         }
+        // A parsed envelope with no text payloads means the run completed but
+        // OpenClaw produced no reply. The raw envelope (sessionFile, usage,
+        // contextBudgetStatus, …) must never reach the chat — that is exactly
+        // what users saw as a wall of JSON. Resolve empty so the caller posts
+        // its clean "no response" notice instead.
+        resolve('');
+        return;
       } catch (e) {
         this._log(`CLI JSON parse error: ${e.message}`);
       }
     }
 
-    // Fallback: return non-diagnostic text
+    // Fallback: return non-diagnostic text. If the output contains an
+    // envelope we failed to parse, suppress it the same way — garbage JSON in
+    // chat is worse than the caller's "no response" notice.
+    if (text.includes('"payloads"')) { resolve(''); return; }
     const cleanLines = text.split('\n').filter(l =>
       !l.includes('[diagnostic]') && !l.includes('[agent/embedded]') && !l.includes('Registered plugin')
     ).map(l => l.trim()).filter(Boolean);

package/src/adapters/opencode.js

@@ -45,6 +45,16 @@ const OPENCODE_TESTED_MAX_VERSION = '1.17.11';
 // window across channels.
 const VERSION_PROBE_TTL_MS = 60000;
 
+// Provider id this adapter writes into the run directory's
+// .opencode/opencode.json when the agent points at a custom OpenAI-compatible
+// gateway. opencode's built-in `openai` provider validates model names against
+// its catalog (a gateway model like `deepseek-4-flash` dies with
+// ProviderModelNotFoundError before any request is sent) and speaks the
+// Responses API (`/v1/responses`), which most gateways don't serve (404 →
+// endless retry). Declaring the gateway as an @ai-sdk/openai-compatible
+// provider keeps requests on `/chat/completions` and skips catalog validation.
+const CUSTOM_PROVIDER_ID = 'openagents-gateway';
+
 // Short, de-identified, actionable user messages per failure category. These
 // must NEVER default to "run auth login": only credential_missing / auth_failed
 // mention authentication. Diagnostics (exit code, signal, redacted stdout/
@@ -670,6 +680,10 @@ class OpenCodeAdapter extends BaseAdapter {
     if (!model) return '';
     // Already provider-qualified (e.g. "openai/gpt-4o", "anthropic/claude-…").
     if (model.includes('/')) return model;
+    // A custom gateway's models aren't in opencode's openai catalog — route
+    // them through the generated openai-compatible provider (see
+    // _ensureCustomProviderConfig).
+    if (this._customBaseUrl()) return `${CUSTOM_PROVIDER_ID}/${model}`;
     // Infer the provider from which key/base URL the env resolved to. The
     // registry maps LLM_* → OPENAI_* for OpenAI-compatible endpoints, so
     // "openai" is the right default; only switch for an Anthropic endpoint.
@@ -680,6 +694,73 @@ class OpenCodeAdapter extends BaseAdapter {
     return `${provider}/${model}`;
   }
 
+  /**
+   * The configured base URL when it points at a custom OpenAI-compatible
+   * gateway, '' for the real OpenAI / Anthropic endpoints (opencode's built-in
+   * providers handle those natively).
+   */
+  _customBaseUrl() {
+    const env = this.agentEnv || process.env;
+    const raw = (env.OPENAI_BASE_URL || env.LLM_BASE_URL || '').trim();
+    if (!raw) return '';
+    let host = '';
+    try { host = new URL(raw).hostname.toLowerCase(); } catch { return ''; }
+    if (host === 'openai.com' || host.endsWith('.openai.com')) return '';
+    if (host === 'anthropic.com' || host.endsWith('.anthropic.com')) return '';
+    return raw;
+  }
+
+  /**
+   * Declare the custom gateway in `<runCwd>/.opencode/opencode.json` so the
+   * `${CUSTOM_PROVIDER_ID}/<model>` id from _resolveModel actually resolves.
+   * Merges into an existing config (only our provider entry is touched); a
+   * file that exists but doesn't parse is left alone — never clobber a config
+   * the user hand-wrote. The API key is referenced as {env:OPENAI_API_KEY}
+   * (resolved by opencode from the spawn env) so it is never written to disk.
+   */
+  _ensureCustomProviderConfig(runCwd) {
+    const baseUrl = this._customBaseUrl();
+    if (!baseUrl) return;
+    const env = this.agentEnv || process.env;
+    const model = (env.OPENCODE_MODEL || env.LLM_MODEL || '').trim();
+    if (!model || model.includes('/')) return;
+
+    const file = path.join(runCwd, '.opencode', 'opencode.json');
+    let cfg = {};
+    try {
+      cfg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+      if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) cfg = {};
+    } catch (e) {
+      if (e && e.code !== 'ENOENT') {
+        this._log(`Not updating ${file} — existing file is unreadable or not valid JSON`);
+        return;
+      }
+    }
+
+    const before = JSON.stringify(cfg);
+    if (!cfg.$schema) cfg.$schema = 'https://opencode.ai/config.json';
+    if (!cfg.provider || typeof cfg.provider !== 'object') cfg.provider = {};
+    const prev = (typeof cfg.provider[CUSTOM_PROVIDER_ID] === 'object' && cfg.provider[CUSTOM_PROVIDER_ID]) || {};
+    cfg.provider[CUSTOM_PROVIDER_ID] = {
+      ...prev,
+      npm: '@ai-sdk/openai-compatible',
+      name: prev.name || 'OpenAgents model gateway',
+      options: { ...(prev.options || {}), baseURL: baseUrl, apiKey: '{env:OPENAI_API_KEY}' },
+      // Keep previously-declared models so switching models doesn't invalidate
+      // sessions that still reference the old id.
+      models: { ...(prev.models || {}), [model]: (prev.models || {})[model] || {} },
+    };
+    if (JSON.stringify(cfg) === before) return;
+
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+      this._log(`Declared gateway provider for ${model} in ${file}`);
+    } catch (e) {
+      this._log(`Failed to write ${file}: ${e.message}`);
+    }
+  }
+
   _runOpencode(content, msgChannel) {
     // Preflight BEFORE spawning: bail out with a structured, actionable error
     // instead of launching a child that will hang for 5 minutes or exit 1 with
@@ -692,6 +773,11 @@ class OpenCodeAdapter extends BaseAdapter {
 
     const binary = this._opencodeBinary;
     const runCwd = this._resolveCwd();
+    // Custom gateways must be declared in the run dir's opencode.json before
+    // the spawn, or --model ${CUSTOM_PROVIDER_ID}/… won't resolve.
+    try { this._ensureCustomProviderConfig(runCwd); } catch (e) {
+      this._log(`Gateway provider config failed (continuing): ${e.message}`);
+    }
     const cmd = [binary, 'run', '--format', 'json', '--dir', runCwd];
 
     // Preflight guarantees a resolvable model; pin it explicitly — without it

package/src/adapters/pi-stream.js

@@ -830,6 +830,33 @@ function isValidSessionId(id) {
  * @param {boolean} [o.trustProject=false]  true → --approve, false → --no-approve
  * @returns {string[]}
  */
+/**
+ * Infer the Launcher-provider settings for a bare relay configuration.
+ *
+ * The workspace's Add-agent flow collects only key + base URL + model, which
+ * lands as PI_API_KEY / PI_BASE_URL / PI_MODEL — no PI_PROVIDER, no
+ * PI_API_FORMAT. The adapter used to refuse that outright ("PI_PROVIDER and
+ * PI_MODEL are required when PI_BASE_URL is set"), a dead end for every agent
+ * created remotely. When the provider is not set explicitly, derive it from
+ * the base URL: anthropic-looking hosts speak anthropic-messages; every other
+ * relay/gateway convention is /chat/completions — NOT OpenAI's /responses, so
+ * the `openai` provider default of openai-responses would be wrong here.
+ * Returns null when PI_PROVIDER is set (explicit config wins) or when there
+ * is no base URL to infer from.
+ */
+function inferLauncherProvider(env = {}) {
+  const val = (k) => String(env[k] == null ? '' : env[k]).trim();
+  if (val('PI_PROVIDER')) return null;
+  const base = val('PI_BASE_URL');
+  if (!base) return null;
+  let host = '';
+  try { host = new URL(base).hostname.toLowerCase(); } catch { host = base.toLowerCase(); }
+  if (host.includes('anthropic')) {
+    return { provider: 'anthropic', apiFormat: 'anthropic-messages' };
+  }
+  return { provider: 'openai', apiFormat: 'openai-completions' };
+}
+
 function buildPiArgs({
   sessionDir,
   sessionId,
@@ -915,6 +942,7 @@ module.exports = {
   parseWindowsCmdShim,
   isValidSessionId,
   buildPiArgs,
+  inferLauncherProvider,
   normalizeThinking,
   parseTrustProject,
   redactArgs,

package/src/adapters/pi.js

@@ -45,6 +45,7 @@ const {
   PiStreamParser,
   PiAssistantAccumulator,
   buildPiArgs,
+  inferLauncherProvider,
   classifyNodeVersion,
   classifyPiError,
   classifyPiVersion,
@@ -1184,6 +1185,17 @@ class PiAdapter extends BaseAdapter {
   /** Environment for the Pi child: agent env plus Pi's own hygiene settings. */
   _buildEnv() {
     const env = { ...(this.agentEnv || process.env) };
+    // A relay-only config (base URL, no explicit provider — what the
+    // workspace's Add-agent flow produces) gets its provider/API format
+    // inferred. Written into the child env so the launcher provider
+    // extension, which reads PI_PROVIDER/PI_API_FORMAT itself, agrees with
+    // the adapter's own view.
+    const inferred = inferLauncherProvider(env);
+    if (inferred) {
+      env.PI_PROVIDER = inferred.provider;
+      const fmt = String(env.PI_API_FORMAT || '').trim().toLowerCase();
+      if (!fmt || fmt === 'auto') env.PI_API_FORMAT = inferred.apiFormat;
+    }
     // The Launcher exposes one provider-agnostic secret field. Pi's native
     // providers still expect their conventional env var, so mirror the value
     // in memory for the child only. Existing provider-specific env remains
@@ -1212,11 +1224,18 @@ class PiAdapter extends BaseAdapter {
   _config() {
     const env = this.agentEnv || process.env;
     const val = (k) => String(env[k] == null ? '' : env[k]).trim();
+    // Same inference as _buildEnv, so the preflight check in _ensureProc
+    // accepts a relay-only config instead of refusing to start.
+    const inferred = inferLauncherProvider(env);
+    const explicitFormat = val('PI_API_FORMAT');
     return {
-      provider: val('PI_PROVIDER') || null,
+      provider: val('PI_PROVIDER') || (inferred && inferred.provider) || null,
       model: val('PI_MODEL') || null,
       baseUrl: val('PI_BASE_URL') || null,
-      apiFormat: val('PI_API_FORMAT') || 'auto',
+      apiFormat:
+        explicitFormat && explicitFormat.toLowerCase() !== 'auto'
+          ? explicitFormat
+          : (inferred && inferred.apiFormat) || explicitFormat || 'auto',
       thinking: normalizeThinking(val('PI_THINKING')),
       trustProject: parseTrustProject(val('PI_TRUST_PROJECT')),
     };

package/src/adapters/workspace-prompt.js

@@ -209,7 +209,7 @@ function buildModePrompt(mode) {
  *
  * In plan mode, only read-only operations are documented.
  */
-function buildApiSkillsPrompt({ endpoint, workspaceId, token, agentName, channelName, disabledModules, mode = 'execute', isWindows = process.platform === 'win32' }) {
+function buildApiSkillsPrompt({ endpoint, workspaceId, token, agentName, channelName, disabledModules, mode = 'execute', isWindows = process.platform === 'win32', execTool = 'exec' }) {
   const disabled = disabledModules || new Set();
   const baseUrl = endpoint.replace(/\/+$/, '');
   const isPlan = mode === 'plan';
@@ -231,14 +231,14 @@ function buildApiSkillsPrompt({ endpoint, workspaceId, token, agentName, channel
     'You can ' + caps.join(', ') + '.\n' +
     'These are WORKSPACE tools shared with all agents and users. ' +
     'They are different from your native tools.\n\n' +
-    '**HOW TO USE:** Call your `exec` tool to run the `curl` commands below. ' +
-    'Do NOT output curl commands as text — EXECUTE them with `exec`.\n\n' +
+    `**HOW TO USE:** Call your \`${execTool}\` tool to run the \`curl\` commands below. ` +
+    `Do NOT output curl commands as text — EXECUTE them with \`${execTool}\`.\n\n` +
     '**IMPORTANT — tool priority:**\n' +
-    '- ALWAYS use `exec` + `curl` (documented below) for workspace operations.\n' +
+    `- ALWAYS use \`${execTool}\` + \`curl\` (documented below) for workspace operations.\n` +
     '- Do NOT use `workspace_browser_*` native tools — they are not configured ' +
     'and will fail.\n' +
     '- Do NOT use `web_fetch`, `browser`, or any native browsing tool ' +
-    'when the user asks to use the workspace browser — use `exec` + `curl` instead.\n' +
+    `when the user asks to use the workspace browser — use \`${execTool}\` + \`curl\` instead.\n` +
     '- The workspace browser is a *shared* browser visible to all users and agents.\n\n' +
     '**Auth header** (include on every request):\n' +
     `\`X-Workspace-Token: ${token}\`\n`
@@ -251,7 +251,7 @@ function buildApiSkillsPrompt({ endpoint, workspaceId, token, agentName, channel
     if (!isPlan) {
       if (isWindows) {
         s += (
-          '**To upload a file**, exec this (replace filename/content):\n' +
+          `**To upload a file**, run this (replace filename/content):\n` +
           `$CONTENT = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('YOUR_CONTENT'))\n` +
           `${curl} -s -X POST ${baseUrl}/v1/files/base64 ` +
           `-H "${h}" ` +
@@ -265,7 +265,7 @@ function buildApiSkillsPrompt({ endpoint, workspaceId, token, agentName, channel
         );
       } else {
         s += (
-          '**To upload a file**, exec this (replace filename/content):\n' +
+          `**To upload a file**, run this (replace filename/content):\n` +
           `CONTENT=$(echo -n 'YOUR_CONTENT' | base64) && ` +
           `${curl} -s -X POST ${baseUrl}/v1/files/base64 ` +
           `-H "${h}" ` +
@@ -354,7 +354,7 @@ function buildApiSkillsPrompt({ endpoint, workspaceId, token, agentName, channel
         `"source":"openagents:${agentName}"}'\n` +
         'If it returns error_code AUTH_REQUIRED or BOT_CHALLENGE, open the URL ' +
         'in a shared tab (below) and share its `live_url` so a human can log in.\n\n' +
-        '**To browse interactively** (click/type/login), exec these steps (use exec for each):\n' +
+        `**To browse interactively** (click/type/login), run these steps (use \`${execTool}\` for each):\n` +
         `Step 1 — open tab: ` +
         `${curl} -s -X POST ${baseUrl}/v1/browser/tabs ` +
         `-H "${h}" -H "Content-Type: application/json" ` +
@@ -1107,6 +1107,39 @@ function buildOpenCodeSkillMd({ endpoint, workspaceId, token, agentName, channel
   return frontmatter + identity + api + '\n' + buildGuardrails();
 }
 
+/**
+ * Build a SKILL.md file for Command Code.
+ *
+ * Command Code discovers skills from `.commandcode/skills/` (project) and
+ * `~/.commandcode/skills/` (user); this file is written to neither. It goes to
+ * an OpenAgents-owned directory and is loaded with `--skill`, so a
+ * token-bearing file never lands in the user's repo or personal config. The
+ * shell tool is named for the CLI that will read it — `shell_command`, not the
+ * `exec` other adapters advertise — because an agent told to call a tool it
+ * does not have simply does nothing.
+ */
+function buildCommandCodeSkillMd({ endpoint, workspaceId, token, agentName, channelName, disabledModules }) {
+  const api = buildApiSkillsPrompt({
+    endpoint, workspaceId, token, agentName,
+    channelName: channelName || 'general',
+    disabledModules,
+    mode: 'execute',
+    execTool: 'shell_command',
+  });
+
+  const frontmatter =
+    '---\n' +
+    `name: ${workspaceSkillName(agentName)}\n` +
+    'description: OpenAgents Workspace API — shared files, browser, and agent collaboration\n' +
+    '---\n\n';
+
+  const identity =
+    `You are agent '${agentName}' connected to OpenAgents workspace ${workspaceId}.\n` +
+    'Use these APIs via `shell_command` + curl to interact with the workspace.\n\n';
+
+  return frontmatter + identity + api + '\n' + buildGuardrails();
+}
+
 /**
  * Build a SKILL.md file for Claude Code's skill auto-discovery.
  *
@@ -1188,6 +1221,7 @@ module.exports = {
   buildOpenclawSkillMd,
   buildOpenCodeSystemPrompt,
   buildOpenCodeSkillMd,
+  buildCommandCodeSkillMd,
   buildPiSystemPrompt,
   buildDeepSeekTaskFile,
   buildClaudeSkillMd,

package/src/cli.js

@@ -54,6 +54,35 @@ function getConnector(flags) {
 
 function print(msg) { process.stdout.write(msg + '\n'); }
 
+// ---------------------------------------------------------------------------
+// Banner — the OpenAgents wordmark (figlet "Small Slant", pure ASCII so it
+// renders on every console including legacy Windows codepages). Colored with
+// a cyan→violet gradient only on a real TTY; pipes and NO_COLOR get plain
+// text. 47 columns wide, so it fits any 80-column terminal.
+// ---------------------------------------------------------------------------
+const OA_LOGO = [
+  '  ____                ___                __    ',
+  ' / __ \\___  ___ ___  / _ |___ ____ ___  / /____',
+  '/ /_/ / _ \\/ -_) _ \\/ __ / _ `/ -_) _ \\/ __(_-<',
+  '\\____/ .__/\\__/_//_/_/ |_\\_, /\\__/_//_/\\__/___/',
+  '    /_/                 /___/                  ',
+];
+
+function printBanner() {
+  const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+  // 256-color gradient, one shade per row: cyan → azure → blue → violet.
+  const shades = [51, 45, 39, 63, 99];
+  let version = '';
+  try { version = require('../package.json').version; } catch {}
+  print('');
+  OA_LOGO.forEach((line, i) => {
+    print(useColor ? `\x1b[38;5;${shades[i]}m${line}\x1b[0m` : line);
+  });
+  const tag = `  v${version} · multi-agent orchestration for your machine`;
+  print(useColor ? `\x1b[2m${tag}\x1b[0m` : tag);
+  print('');
+}
+
 function table(rows, headers) {
   if (rows.length === 0) return;
   const widths = headers.map((h, i) =>
@@ -178,7 +207,18 @@ async function cmdCreate(connector, flags, positional) {
       print('This agent is local-only and will not appear in Workspace Dashboard yet.');
       print('');
       print('To connect it to a Workspace, run:');
-      print(`  agn connect ${name} <workspace-token>`);
+      // A paired device already holds the credential — point at the
+      // pairing-first form instead of the deprecated manual-token one.
+      let pairings = [];
+      try { pairings = require('./node-config').listPairings().filter((p) => p && p.workspace_slug); } catch {}
+      if (pairings.length) {
+        for (const p of pairings.slice(0, 3)) {
+          print(`  agn connect ${name} --workspace ${p.workspace_slug}${p.workspace_name ? `   (${p.workspace_name})` : ''}`);
+        }
+      } else {
+        print(`  agn connect ${name} <workspace-token>`);
+        print('Or pair this device first: agn node connect <pairing-code>');
+      }
     } else {
       print(`Agent '${name}' created (type: ${type})`);
     }
@@ -323,6 +363,24 @@ async function cmdRuntimes(connector, flags) {
     const runtimes = connector.registry.getCatalogSync().map((e) => {
       let h;
       try { h = connector.healthCheck(e.name); } catch { h = {}; }
+      // Credential contract, upward half: STATUS goes up, the secret stays on
+      // this device. `mode` says how the type authenticates today
+      // (subscription = CLI/OAuth login, api_key = a stored key, none = not
+      // configured); keyMasked shows only the key's tail.
+      let keyMasked = null;
+      try {
+        const env = connector.env.load(e.name) || {};
+        const key = env.LLM_API_KEY || null;
+        if (key && key.length > 7) keyMasked = `…${key.slice(-4)}`;
+        else if (key) keyMasked = '…';
+      } catch {}
+      const mode = !h.ready
+        ? 'none'
+        : h.auth_mode === 'cli_login'
+          ? 'subscription'
+          : h.auth_mode === 'api_key'
+            ? 'api_key'
+            : 'none';
       return {
         type: e.name,
         installed: !!h.installed,
@@ -331,6 +389,7 @@ async function cmdRuntimes(connector, flags) {
         reason: h.reason || null,
         message: h.message || null,
         authStatus: h.auth_status || null,
+        auth: { mode, keyMasked: mode === 'api_key' ? keyMasked : null },
       };
     });
     process.stdout.write(JSON.stringify(runtimes));
@@ -372,10 +431,20 @@ async function cmdConnect(connector, flags, positional) {
 
   if (!name) {
     print('Usage: agn connect <agent-name> <token>');
+    print('       agn connect <agent-name> --workspace <slug>   (paired/known workspace, no token)');
     process.exitCode = 1;
     return;
   }
 
+  // --workspace <slug|id>: bind to a workspace this device already knows —
+  // a registered network or a device pairing. No token, no /v1/token/resolve,
+  // no server round-trip; the credential is already on disk. This is the
+  // pairing-first path; the token form below stays for manual connection.
+  if (flags.workspace && typeof flags.workspace === 'string') {
+    connectKnownWorkspace(connector, name, flags.workspace);
+    return;
+  }
+
   if (!token) {
     // No token supplied and none in the environment. Never prompt — keep
     // CI / non-interactive environments from hanging. Print a helpful error
@@ -406,6 +475,14 @@ async function cmdConnect(connector, flags, positional) {
     // Connect agent
     connector.connectWorkspace(name, slug);
     print(`'${name}' connected to workspace '${wsName}'`);
+    // Manual token connection is being retired in favor of device pairing.
+    // It keeps working (backward compatibility is deliberate); this is the
+    // CLI half of the dismissible launcher notice.
+    if (!process.env.OPENAGENTS_NO_DEPRECATION_NOTES) {
+      print('note: manual token connection is being retired in favor of device pairing.');
+      print('      Pair once with `agn node connect <code>`, then `agn connect <agent> --workspace <slug>`.');
+      print('      (Silence this note with OPENAGENTS_NO_DEPRECATION_NOTES=1.)');
+    }
 
     // Signal daemon reload
     const pid = connector.getDaemonPid();
@@ -421,6 +498,78 @@ async function cmdConnect(connector, flags, positional) {
   }
 }
 
+/**
+ * Bind an agent to a workspace already known to this device, by slug or id.
+ * Sources, in order: registered networks (daemon.yaml), then device pairings
+ * (node.json) — a pairing registers its network on the spot so the daemon can
+ * pick up the token. Never touches the server.
+ */
+function connectKnownWorkspace(connector, name, ref) {
+  const networks = connector.config.getNetworks() || [];
+  let net = networks.find((n) => n.slug === ref || n.id === ref);
+
+  if (!net) {
+    const nodeCfg = require('./node-config');
+    const pairing = (nodeCfg.listPairings() || []).find(
+      (p) => p.workspace_slug === ref || p.workspace_id === ref,
+    );
+    if (pairing && pairing.token) {
+      connector.config.addNetwork({
+        id: pairing.workspace_id,
+        slug: pairing.workspace_slug,
+        name: pairing.workspace_name || pairing.workspace_slug,
+        endpoint: pairing.endpoint || connector.workspace.endpoint,
+        token: pairing.token,
+      });
+      net = { slug: pairing.workspace_slug, name: pairing.workspace_name };
+    }
+  }
+
+  if (!net) {
+    const known = [
+      ...new Set([
+        ...networks.map((n) => n.slug || n.id),
+        ...(() => {
+          try {
+            return require('./node-config').listPairings().map((p) => p.workspace_slug);
+          } catch { return []; }
+        })(),
+      ]),
+    ].filter(Boolean);
+    print(`No workspace '${ref}' is known on this device.`);
+    if (known.length) print(`Known workspaces: ${known.join(', ')}`);
+    print('Pair this device first (`agn node connect <code>`), or connect with a token.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const slug = net.slug || ref;
+  connector.connectWorkspace(name, slug);
+  print(`'${name}' connected to workspace '${net.name || slug}'`);
+
+  const pid = connector.getDaemonPid();
+  if (pid) {
+    connector.sendDaemonCommand(`restart:${name}`);
+    print('Daemon notified');
+  } else {
+    print('Daemon is not running. Run `agn up` to bring this agent online.');
+  }
+}
+
+/**
+ * Browser URL of a workspace, matching the TUI's convention: a localhost/dev
+ * endpoint serves its own web app; everything else lives on the hosted
+ * dashboard. This is what a freshly paired user actually needs next — NOT
+ * another CLI command.
+ */
+function workspaceWebUrl(slug, endpoint) {
+  const ep = String(endpoint || '');
+  const isLocal = ep.includes('localhost') || ep.includes('127.0.0.1');
+  return isLocal
+    ? `${ep.replace(/\/+$/, '')}/${slug}`
+    : `https://workspace.openagents.org/${slug}`;
+}
+
 async function cmdNode(connector, flags, positional) {
   const sub = positional[0] || 'status';
   const nodeCfg = require('./node-config');
@@ -437,9 +586,28 @@ async function cmdNode(connector, flags, positional) {
     if (flags.type) info.deviceType = flags.type;   // server | laptop | desktop
     if (flags.name) info.name = flags.name;
 
+    // Existing pairings up front, so a re-run shows where this device already
+    // lives instead of looking like a first-time setup.
+    const priorPairings = nodeCfg.listPairings().filter((p) => p.node_id);
+    if (priorPairings.length) {
+      print('This device is already paired with:');
+      for (const p of priorPairings) {
+        print(`  ${p.workspace_name || p.workspace_slug} — ${workspaceWebUrl(p.workspace_slug || p.workspace_id, p.endpoint)}`);
+      }
+      print('');
+    }
+
     print('Connecting this device to your workspace...');
     try {
       const res = await connector.redeemNodePairingCode(code, info);
+      // A code always redeems against ONE workspace; if that workspace is one
+      // this device already belongs to, this is a re-pair, not a new pairing.
+      // recordPairing below still runs — it refreshes the (possibly rotated)
+      // credential in place — but the user should hear "already paired", not
+      // a duplicate "connected".
+      const alreadyPaired = priorPairings.some(
+        (p) => p.workspace_id === res.workspaceId,
+      );
       // recordPairing, not saveNode: this device can be a node in several
       // workspaces at once, and a bare save would drop the others' pairings.
       nodeCfg.recordPairing(info.nodeKey, {
@@ -458,7 +626,11 @@ async function cmdNode(connector, flags, positional) {
         endpoint: connector.workspace.endpoint,
         token: res.token,
       });
-      print(`Node connected to workspace '${res.workspaceName}' (${res.workspaceSlug})`);
+      if (alreadyPaired) {
+        print(`Already paired with '${res.workspaceName}' (${res.workspaceSlug}) — refreshed this device's credential.`);
+      } else {
+        print(`Node connected to workspace '${res.workspaceName}' (${res.workspaceSlug})`);
+      }
       print(`  This device: ${info.hostname} (${info.deviceType})`);
 
       // (Re)start the daemon so it runs the CURRENT launcher build and loads
@@ -476,8 +648,10 @@ async function cmdNode(connector, flags, positional) {
       }
       connector.startDaemon();
       print('');
-      print('Next: add an agent from the workspace, or run:');
-      print('  agn create <name> --type <type> --install');
+      // The user came from the workspace's "Connect a Node" page — send them
+      // straight back there with a clickable link, not more CLI homework.
+      print('All set! Open your workspace to add and manage agents on this device:');
+      print(`  ${workspaceWebUrl(res.workspaceSlug, connector.workspace.endpoint)}`);
     } catch (e) {
       print(`Error: ${e.message}`);
       process.exitCode = 1;
@@ -493,7 +667,8 @@ async function cmdNode(connector, flags, positional) {
     }
     print(`Node connected to ${pairings.length} workspace(s):`);
     for (const p of pairings) {
-      print(`  ${p.workspace_slug || p.workspace_id} — node ${p.node_id}`);
+      const slug = p.workspace_slug || p.workspace_id;
+      print(`  ${p.workspace_name || slug} (${slug}) — ${workspaceWebUrl(slug, p.endpoint)}`);
     }
     return;
   }
@@ -882,6 +1057,7 @@ async function cmdUpdate(connector) {
 }
 
 async function cmdHelp() {
+  printBanner();
   print(`Usage: agn <command> [options]
 
 Commands:
@@ -898,7 +1074,7 @@ Commands:
   uninstall <type>            Uninstall an agent runtime
   search [query]              Browse agent catalog
   runtimes                    List installed runtimes
-  connect <agent> <token>     Connect agent to workspace
+  connect <agent> <token>     Connect agent to workspace (or --workspace <slug> for a paired one)
   disconnect <agent>          Disconnect agent from workspace
   env <type> [--set K=V]      View/set env vars for agent type
   skills [agent] [action]     Manage agent skills (enable/disable)

package/src/config.js

@@ -116,8 +116,19 @@ class Config {
 
   addNetwork({ id, slug, name, endpoint, token }) {
     const config = this.load();
-    if (config.networks.some((n) => n.slug === slug || n.id === id)) {
-      return; // already exists
+    // Upsert, not insert-only: re-registering a known workspace refreshes its
+    // credentials. The old early-return silently kept a stale token after a
+    // rotation or re-pair — both the launcher and the CLI then had to carry
+    // their own read-modify-write patches around it.
+    const existing = config.networks.find((n) => n.slug === slug || n.id === id);
+    if (existing) {
+      if (id) existing.id = id;
+      if (slug) existing.slug = slug;
+      if (name) existing.name = name;
+      if (endpoint) existing.endpoint = endpoint;
+      if (token) existing.token = token;
+      this.save(config);
+      return existing;
     }
     const entry = { id, slug };
     if (name) entry.name = name;