Merge remote-tracking branch 'origin/main' into setup-root-warning-v2

# Conflicts:
#	setup/auto.ts

CLAUDE.md

@@ -157,6 +157,17 @@ Four types of skills. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full taxono
 
 Before creating a PR, adding a skill, or preparing any contribution, you MUST read [CONTRIBUTING.md](CONTRIBUTING.md). It covers accepted change types, the four skill types and their guidelines, `SKILL.md` format rules, and the pre-submission checklist.
 
+## PR Hygiene
+
+Before creating a PR, run these checks:
+
+```bash
+git diff upstream/main --stat HEAD
+git log upstream/main..HEAD --oneline
+```
+
+Show the output and wait for approval. Installation-specific files (group files, .claude/settings.json, local configs) should not be included.
+
 ## Development
 
 Run commands directly — don't tell the user to run them.

CONTRIBUTING.md

@@ -123,7 +123,8 @@ Test your contribution on a fresh clone before submitting. For skills, run the s
 
 1. **Link related issues.** If your PR resolves an open issue, include `Closes #123` in the description so it's auto-closed on merge.
 2. **Test thoroughly.** Run the feature yourself. For skills, test on a fresh clone.
-3. **Check the right box** in the PR template. Labels are auto-applied based on your selection:
+3. **Check for installation-specific files.** Before creating a PR, verify no installation-specific files are in your diff (see PR Hygiene in CLAUDE.md).
+4. **Check the right box** in the PR template. Labels are auto-applied based on your selection:
 
 | Checkbox | Label |
 |----------|-------|

assets/setup-splash.txt

@@ -0,0 +1,30 @@
+
+     ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠰⣄⠘⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀   
+     ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢹⡆⢸⡆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀  °
+     ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⢸⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀   
+     ⠀⠀⠀⠀⠀⢀⣠⣴⠾⠟⠛⠛⠿⢶⣦⣾⠇⣾⠁⠀⠀⠀⢀⣤⣤⠀⢀⣄⠀   
+     ⠀⠀⠀⠀⣴⡿⡋⠀⠀⠀⠀⠀⢤⣾⣿⢛⢿⣏⠀⠀⠀⢰⣟⣽⡏⠀⣸⡿⣧   
+   o ⠀⠀⢀⣾⠋⠀⠀⠀⠀⠀⠀⠀⠀⠘⠈⣧⣀⣿⣧⠀⠀⣿⣼⣿⣇⣾⠋⢠⣿   
+     ⠀⠀⣾⢃⠀⢲⣷⡋⣰⡀⢀⣀⣀⡀⠠⣿⣿⣠⣿⣇⠀⣿⢻⣉⠉⠙⠠⣼⠇   
+     ⠀⣼⡏⠃⠀⢸⣿⣿⡿⠃⣾⣷⣻⣿⡏⢹⠿⠿⣿⣿⢀⣿⣐⠙⣷⣦⡾⠋⠀  o
+     ⢠⣿⡃⠀⠀⠀⠀⠀⠈⠀⠀⠉⠙⠁⠀⠀⠀⠐⣿⣿⣟⠁⣿⣿⠟⠋⠀⠀⠀   
+   ° ⢸⣿⣧⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣨⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀⠀   
+     ⢸⣿⣿⣷⣤⣤⠀⣀⢀⠀⢀⣀⣠⣴⣶⣿⣿⣿⣿⡿⠛⠁⠀⠀⠀⠀⠀⠀⠀   
+     ⣿⢋⠿⣿⣿⣿⣿⡿⣿⣿⣿⣿⣿⣿⠿⠿⠿⣿⣅⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀  O
+     ⣿⣿⠙⢾⣽⣟⣿⣿⣼⣿⣿⣿⣩⣶⣶⣦⠀⠀⠩⢻⣆⠀⠀⠀⠀⠀⠀⠀⠀   
+     ⠘⣿⣶⣤⣿⣿⣿⣿⣵⢖⡀⠉⠹⡛⢷⣝⡿⠁⠀⠀⣿⡆⠀⠀⠀⠀⠀⠀⠀   
+     ⠀⢹⣯⣽⣟⣛⣻⣿⣿⣾⣽⢶⣽⣿⣿⣿⣏⠀⠠⣤⣿⡇⠀⠀⠀⠀⠀⠀⠀   
+     ⠀⠀⠻⣿⣶⣾⣿⢿⣻⣿⣿⣿⣿⣿⣿⣏⣛⣧⣦⣿⣿⣧⣄⠀⠀⠀⠀⠀⠀   
+   o ⠀⠀⠀⠈⠻⣿⣶⣥⣼⣿⣿⣽⣿⣿⣿⣷⣶⣾⣿⣿⣯⣘⣿⣧⠀⠀⠀⠀⠀   
+     ⠀⠀⠀⠀⠤⣤⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⠿⠿⠋⠀⠀⠀⠀⠀   
+
+ _  _                 ___ _             
+| \| |__ _ _ _  ___  / __| |__ ___ __ __
+| .` / _` | ' \/ _ \| (__| / _` \ V  V /
+|_|\_\__,_|_||_\___/ \___|_\__,_|\_/\_/ 
+
+                 Small.
+         Runs on your machine.
+            Yours to modify.
+
+════════════════════════════════════════

container/agent-runner/src/providers/claude.ts

@@ -226,8 +226,12 @@ function createPreCompactHook(assistantName?: string): HookCallback {
 /**
  * Claude Code auto-compacts context at this window (tokens). Kept here so
  * the generic bootstrap doesn't need to know about Claude-specific env vars.
+ *
+ * Operator override: set CLAUDE_CODE_AUTO_COMPACT_WINDOW in the host env to
+ * raise or lower the threshold without editing source — useful when running
+ * with a 1M-context model variant or when emergency-tuning a deployment.
  */
-const CLAUDE_CODE_AUTO_COMPACT_WINDOW = '165000';
+const CLAUDE_CODE_AUTO_COMPACT_WINDOW = process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW || '165000';
 
 /**
  * Stale-session detection. Matches Claude Code's error text when a

nanoclaw.sh

@@ -129,10 +129,13 @@ rm -f  "$PROGRESS_LOG"
 mkdir -p "$STEPS_DIR" "$LOGS_DIR"
 write_header
 
-# NanoClaw wordmark — clack's intro carries the "let's get you set up" framing,
-# so we don't print a subtitle here. setup:auto sees NANOCLAW_BOOTSTRAPPED=1 and
-# skips re-printing the wordmark, keeping the flow visually continuous.
-printf '\n  %s%s\n\n' "$(bold 'Nano')" "$(brand_bold 'Claw')"
+# NanoClaw splash — under-the-sea lobster mascot in truecolor braille,
+# with the figlet wordmark and taglines below. Pre-rendered into
+# assets/setup-splash.txt (built from assets/nanoclaw-icon.png via chafa +
+# figlet); the bash script just streams the literal frame. clack's intro
+# then carries the "let's get you set up" framing — setup:auto sees
+# NANOCLAW_BOOTSTRAPPED=1 and skips re-printing the wordmark.
+cat "$PROJECT_ROOT/assets/setup-splash.txt"
 
 # ─── pre-flight: root user warning (Linux) ────────────────────────────
 if [ "$(uname -s)" = "Linux" ] && [ "$(id -u)" -eq 0 ]; then
@@ -221,9 +224,6 @@ BOOTSTRAP_RAW="${STEPS_DIR}/01-bootstrap.log"
 BOOTSTRAP_LABEL="Installing the basics"
 BOOTSTRAP_START=$(date +%s)
 
-# One-line "why" that teaches a differentiator while the user waits.
-printf '%s  %s\n' "$(gray '│')" \
-  "$(dim "Small. Runs on your machine. Yours to modify.")"
 spinner_start "$BOOTSTRAP_LABEL"
 
 # Run in the background so we can tick elapsed time. Capture exit code via

package.json

@@ -1,6 +1,6 @@
 {
   "name": "nanoclaw",
-  "version": "2.0.15",
+  "version": "2.0.20",
   "description": "Personal Claude assistant. Lightweight, secure, customizable.",
   "type": "module",
   "packageManager": "pnpm@10.33.0",

repo-tokens/badge.svg

@@ -1,5 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="90" height="20" role="img" aria-label="133k tokens, 67% of context window">
-  <title>133k tokens, 67% of context window</title>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="90" height="20" role="img" aria-label="138k tokens, 69% of context window">
+  <title>138k tokens, 69% of context window</title>
   <linearGradient id="s" x2="0" y2="100%">
     <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
     <stop offset="1" stop-opacity=".1"/>
@@ -15,8 +15,8 @@
       <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
         <text aria-hidden="true" x="26" y="15" fill="#010101" fill-opacity=".3">tokens</text>
         <text x="26" y="14">tokens</text>
-        <text aria-hidden="true" x="71" y="15" fill="#010101" fill-opacity=".3">133k</text>
-        <text x="71" y="14">133k</text>
+        <text aria-hidden="true" x="71" y="15" fill="#010101" fill-opacity=".3">138k</text>
+        <text x="71" y="14">138k</text>
       </g>
     </g>
   </a>

setup/auto.ts

@@ -53,7 +53,7 @@ import { claudeCliAvailable, resolveTimezoneViaClaude } from './lib/tz-from-clau
 import * as setupLog from './logs.js';
 import { ensureAnswer, fail, runQuietChild, runQuietStep } from './lib/runner.js';
 import { emit as phEmit } from './lib/diagnostics.js';
-import { brandBold, brandChip, dimWrap, fitToWidth, note, wrapForGutter } from './lib/theme.js';
+import { accentGreen, brandBody, brandBold, brandChip, dimWrap, fitToWidth, fmtDuration, note, wrapForGutter } from './lib/theme.js';
 import { isValidTimezone } from '../src/timezone.js';
 
 const CLI_AGENT_NAME = 'Terminal Agent';
@@ -126,51 +126,14 @@ async function main(): Promise<void> {
     }
   }
 
-  // Detect existing .env and offer to reuse it so the user doesn't have to
-  // paste credentials again on a re-run.
-  const existingEnv = detectExistingEnv();
-  if (existingEnv) {
-    // On sg re-exec, auto-reuse — the user already decided in the first run.
-    const isReexec = process.env.NANOCLAW_REEXEC_SG === '1';
-    let reuseChoice: 'reuse' | 'fresh' = 'reuse';
-
-    if (!isReexec) {
-      const lines = Object.values(existingEnv.groups).map(
-        (g) => `  ${k.green('✓')} ${g.label}`,
-      );
-      note(lines.join('\n'), 'Found existing configuration');
-
-      reuseChoice = ensureAnswer(
-        await brightSelect({
-          message: 'Use this existing environment?',
-          options: [
-            { value: 'reuse', label: 'Yes, use what I already have', hint: 'recommended' },
-            { value: 'fresh', label: 'No, start fresh' },
-          ],
-          initialValue: 'reuse',
-        }),
-      ) as 'reuse' | 'fresh';
-      setupLog.userInput('existing_env_choice', reuseChoice);
-    }
-
-    if (reuseChoice === 'reuse') {
-      for (const [key, value] of Object.entries(existingEnv.raw)) {
-        if (!process.env[key]) process.env[key] = value;
-      }
-      if (existingEnv.groups.onecli) skip.add('onecli');
-      if (detectRegisteredGroups(process.cwd())) {
-        skip.add('cli-agent');
-        skip.add('first-chat');
-      }
-    }
-  }
-
   if (!skip.has('container')) {
-    p.log.message(dimWrap('Your assistant lives in its own sandbox. It can only see what you explicitly share.', 4));
+    p.log.message(brandBody(dimWrap('Your assistant lives in its own sandbox. It can only see what you explicitly share.', 4)));
     p.log.message(
-      dimWrap(
-        'The first build pulls a base image and installs a few tools. On a fresh machine this usually takes 3–10 minutes.',
-        4,
+      brandBody(
+        dimWrap(
+          'The first build pulls a base image and installs a few tools. On a fresh machine this usually takes 3–10 minutes.',
+          4,
+        ),
       ),
     );
     const res = await runWindowedStep('container', {
@@ -205,9 +168,11 @@ async function main(): Promise<void> {
 
   if (!skip.has('onecli')) {
     p.log.message(
-      dimWrap(
-        'Your assistant never gets your API keys directly. The vault adds them to approved requests as they leave the sandbox.',
-        4,
+      brandBody(
+        dimWrap(
+          'Your assistant never gets your API keys directly. The vault adds them to approved requests as they leave the sandbox.',
+          4,
+        ),
       ),
     );
 
@@ -331,9 +296,11 @@ async function main(): Promise<void> {
       await fail('service', "Couldn't start NanoClaw.", 'See logs/nanoclaw.error.log for details.');
     }
     if (res.terminal?.fields.DOCKER_GROUP_STALE === 'true') {
-      p.log.warn("NanoClaw's permissions need a tweak before it can reach Docker.");
+      p.log.warn(brandBody("NanoClaw's permissions need a tweak before it can reach Docker."));
       p.log.message(
-        '  sudo setfacl -m u:$(whoami):rw /var/run/docker.sock\n' + `  systemctl --user restart ${getSystemdUnit()}`,
+        brandBody(
+          '  sudo setfacl -m u:$(whoami):rw /var/run/docker.sock\n' + `  systemctl --user restart ${getSystemdUnit()}`,
+        ),
       );
     }
   }
@@ -348,6 +315,11 @@ async function main(): Promise<void> {
     return displayName;
   }
 
+  if (!skip.has('cli-agent') && detectRegisteredGroups(process.cwd())) {
+    skip.add('cli-agent');
+    skip.add('first-chat');
+  }
+
   if (!skip.has('cli-agent')) {
     await resolveDisplayName();
     const res = await runQuietStep(
@@ -367,16 +339,18 @@ async function main(): Promise<void> {
     }
     if (!skip.has('first-chat')) {
       p.log.message(
-        dimWrap(
-          "Your assistant runs in an isolated sandbox. I'm going to send it a quick test message (ping) and wait for a reply (pong) to confirm it's responding. First startup typically takes 30–60 seconds while the sandbox warms up.",
-          4,
+        brandBody(
+          dimWrap(
+            "Your assistant runs in an isolated sandbox. I'm going to send it a quick test message (ping) and wait for a reply (pong) to confirm it's responding. First startup typically takes 30–60 seconds while the sandbox warms up.",
+            4,
+          ),
         ),
       );
       const ping = await confirmAssistantResponds();
       if (ping === 'ok') {
         phEmit('first_chat_ready');
         const next = ensureAnswer(
-          await p.select({
+          await brightSelect<'continue' | 'chat'>({
             message: 'What next?',
             options: [
               {
@@ -437,9 +411,11 @@ async function main(): Promise<void> {
       await runIMessageChannel(displayName!);
     } else {
       p.log.info(
-        wrapForGutter(
-          'No messaging app for now. You can add one later (like Telegram, Discord, WhatsApp, Teams, Slack, or iMessage).',
-          4,
+        brandBody(
+          wrapForGutter(
+            'No messaging app for now. You can add one later (like Telegram, Discord, WhatsApp, Teams, Slack, or iMessage).',
+            4,
+          ),
         ),
       );
     }
@@ -579,18 +555,16 @@ async function confirmAssistantResponds(): Promise<PingResult> {
   const s = p.spinner();
   const start = Date.now();
   const label = 'Waking your assistant…';
-  s.start(fitToWidth(label, ' (999s)'));
+  s.start(fitToWidth(label, ' (99m 59s)'));
   const tick = setInterval(() => {
-    const elapsed = Math.round((Date.now() - start) / 1000);
-    const suffix = ` (${elapsed}s)`;
+    const suffix = ` (${fmtDuration(Date.now() - start)})`;
     s.message(`${fitToWidth(label, suffix)}${k.dim(suffix)}`);
   }, 1000);
 
   const result = await pingCliAgent();
 
   clearInterval(tick);
-  const elapsed = Math.round((Date.now() - start) / 1000);
-  const suffix = ` (${elapsed}s)`;
+  const suffix = ` (${fmtDuration(Date.now() - start)})`;
   if (result === 'ok') {
     s.stop(`${k.bold(fitToWidth('Your assistant is ready.', suffix))}${k.dim(suffix)}`);
   } else {
@@ -679,7 +653,7 @@ function sendChatMessage(message: string): Promise<void> {
 
 async function runAuthStep(): Promise<void> {
   if (anthropicSecretExists()) {
-    p.log.success('Your Claude account is already connected.');
+    p.log.success(brandBody('Your Claude account is already connected.'));
     setupLog.step('auth', 'skipped', 0, { REASON: 'secret-already-present' });
     return;
   }
@@ -727,7 +701,7 @@ async function runAuthStep(): Promise<void> {
 }
 
 async function runSubscriptionAuth(): Promise<void> {
-  p.log.step('Opening the Claude sign-in flow…');
+  p.log.step(brandBody('Opening the Claude sign-in flow…'));
   console.log(k.dim('   (a browser will open for sign-in; this part is interactive)'));
   console.log();
   const start = Date.now();
@@ -746,7 +720,7 @@ async function runSubscriptionAuth(): Promise<void> {
     );
   }
   setupLog.step('auth', 'interactive', durationMs, { METHOD: 'subscription' });
-  p.log.success('Claude account connected.');
+  p.log.success(brandBody('Claude account connected.'));
 }
 
 async function runPasteAuth(method: 'oauth' | 'api'): Promise<void> {
@@ -970,9 +944,11 @@ async function runTimezoneStep(): Promise<void> {
       tz = await resolveTimezoneViaClaude(raw);
     } else {
       p.log.warn(
-        wrapForGutter(
-          "That's not a standard IANA zone and I can't call Claude to interpret it here — try again with a zone like `America/New_York` or `Europe/London`.",
-          4,
+        brandBody(
+          wrapForGutter(
+            "That's not a standard IANA zone and I can't call Claude to interpret it here — try again with a zone like `America/New_York` or `Europe/London`.",
+            4,
+          ),
         ),
       );
     }
@@ -1015,7 +991,7 @@ async function runTimezoneStep(): Promise<void> {
 async function askDisplayName(fallback: string): Promise<string> {
   const answer = ensureAnswer(
     await p.text({
-      message: 'What should your assistant call you?',
+      message: `What should your assistant call ${accentGreen('you')}?`,
       placeholder: fallback,
       defaultValue: fallback,
     }),
@@ -1061,56 +1037,6 @@ async function askChannelChoice(): Promise<ChannelChoice> {
 
 // ─── interactive / env helpers ─────────────────────────────────────────
 
-interface ExistingEnvGroup {
-  label: string;
-  keys: string[];
-}
-
-const ENV_KEY_GROUPS: Record<string, { label: string; keys: string[] }> = {
-  onecli: { label: 'OneCLI', keys: ['ONECLI_URL'] },
-  telegram: { label: 'Telegram', keys: ['TELEGRAM_BOT_TOKEN'] },
-  discord: { label: 'Discord', keys: ['DISCORD_BOT_TOKEN', 'DISCORD_APPLICATION_ID', 'DISCORD_PUBLIC_KEY'] },
-  slack: { label: 'Slack', keys: ['SLACK_BOT_TOKEN', 'SLACK_SIGNING_SECRET'] },
-  signal: { label: 'Signal', keys: ['SIGNAL_ACCOUNT'] },
-  teams: { label: 'Teams', keys: ['TEAMS_APP_ID', 'TEAMS_APP_PASSWORD', 'TEAMS_APP_TENANT_ID', 'TEAMS_APP_TYPE'] },
-  whatsapp: { label: 'WhatsApp', keys: ['ASSISTANT_HAS_OWN_NUMBER'] },
-  imessage: { label: 'iMessage', keys: ['IMESSAGE_LOCAL', 'IMESSAGE_ENABLED', 'IMESSAGE_SERVER_URL', 'IMESSAGE_API_KEY'] },
-};
-
-function detectExistingEnv(): { groups: Record<string, ExistingEnvGroup>; raw: Record<string, string> } | null {
-  const envPath = path.join(process.cwd(), '.env');
-  if (!fs.existsSync(envPath)) return null;
-
-  let content: string;
-  try {
-    content = fs.readFileSync(envPath, 'utf-8');
-  } catch {
-    return null;
-  }
-
-  const raw: Record<string, string> = {};
-  for (const line of content.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const eq = trimmed.indexOf('=');
-    if (eq < 1) continue;
-    raw[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
-  }
-
-  if (Object.keys(raw).length === 0) return null;
-
-  const groups: Record<string, ExistingEnvGroup> = {};
-  for (const [id, def] of Object.entries(ENV_KEY_GROUPS)) {
-    const found = def.keys.filter((key) => raw[key] !== undefined);
-    if (found.length > 0) {
-      groups[id] = { label: def.label, keys: found };
-    }
-  }
-
-  if (Object.keys(groups).length === 0) return null;
-  return { groups, raw };
-}
-
 function anthropicSecretExists(): boolean {
   try {
     const res = spawnSync('onecli', ['secrets', 'list'], {
@@ -1187,7 +1113,7 @@ function maybeReexecUnderSg(): void {
   if (!/permission denied/i.test(err)) return;
   if (spawnSync('which', ['sg'], { stdio: 'ignore' }).status !== 0) return;
 
-  p.log.warn('Docker socket not accessible in current group. Re-executing under `sg docker`.');
+  p.log.warn(brandBody('Docker socket not accessible in current group. Re-executing under `sg docker`.'));
   const existingSkip = (process.env.NANOCLAW_SKIP ?? '').split(',').map((s) => s.trim()).filter(Boolean);
   const skipList = [...new Set([...existingSkip, ...setupLog.completedStepNames()])].join(',');
   const res = spawnSync('sg', ['docker', '-c', 'pnpm run setup:auto'], {

setup/channels/discord.ts

@@ -28,10 +28,11 @@ import k from 'kleur';
 
 import * as setupLog from '../logs.js';
 import { brightSelect } from '../lib/bright-select.js';
-import { confirmThenOpen } from '../lib/browser.js';
+import { confirmThenOpen, formatNoteLink } from '../lib/browser.js';
 import { askOperatorRole } from '../lib/role-prompt.js';
 import { ensureAnswer, fail, runQuietChild } from '../lib/runner.js';
-import { note } from '../lib/theme.js';
+import { readEnvKey } from '../environment.js';
+import { accentGreen, brandBody, fmtDuration, note } from '../lib/theme.js';
 
 const DEFAULT_AGENT_NAME = 'Nano';
 const DISCORD_API = 'https://discord.com/api/v10';
@@ -164,9 +165,8 @@ async function walkThroughBotCreation(): Promise<void> {
       '  2. In the "Bot" tab, click "Reset Token" and copy the token',
       '  3. On the same tab, enable "Message Content Intent"',
       '     (under Privileged Gateway Intents)',
-      '',
-      k.dim(url),
-    ].join('\n'),
+      formatNoteLink(url),
+    ].filter((line): line is string => line !== null).join('\n'),
     'Create a Discord bot',
   );
   await confirmThenOpen(url, 'Press Enter to open the Developer Portal');
@@ -224,9 +224,8 @@ async function walkThroughServerCreation(): Promise<void> {
       '  1. In Discord, click the "+" at the bottom of the server list',
       '  2. Choose "Create My Own" → "For me and my friends"',
       '  3. Give it any name (e.g. "NanoClaw")',
-      '',
-      k.dim(url),
-    ].join('\n'),
+      formatNoteLink(url),
+    ].filter((line): line is string => line !== null).join('\n'),
     'Create a Discord server',
   );
   await confirmThenOpen(url, 'Press Enter to open Discord');
@@ -240,7 +239,7 @@ async function walkThroughServerCreation(): Promise<void> {
 }
 
 async function collectDiscordToken(): Promise<string> {
-  const existing = process.env.DISCORD_BOT_TOKEN?.trim();
+  const existing = readEnvKey('DISCORD_BOT_TOKEN');
   if (existing && /^[A-Za-z0-9._-]{50,}$/.test(existing)) {
     const reuse = ensureAnswer(await p.confirm({
       message: `Found an existing Discord bot token (${existing.slice(0, 10)}…). Use it?`,
@@ -289,9 +288,8 @@ async function validateDiscordToken(token: string): Promise<string> {
       username?: string;
       message?: string;
     };
-    const elapsedS = Math.round((Date.now() - start) / 1000);
     if (res.ok && data.username) {
-      s.stop(`Found your bot: @${data.username}. ${k.dim(`(${elapsedS}s)`)}`);
+      s.stop(`Found your bot: @${data.username}. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`);
       setupLog.step('discord-validate', 'success', Date.now() - start, {
         BOT_USERNAME: data.username,
         BOT_ID: data.id ?? '',
@@ -309,8 +307,7 @@ async function validateDiscordToken(token: string): Promise<string> {
       'Copy the token again from the Developer Portal and retry setup.',
     );
   } catch (err) {
-    const elapsedS = Math.round((Date.now() - start) / 1000);
-    s.stop(`Couldn't reach Discord. ${k.dim(`(${elapsedS}s)`)}`, 1);
+    s.stop(`Couldn't reach Discord. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`, 1);
     const message = err instanceof Error ? err.message : String(err);
     setupLog.step('discord-validate', 'failed', Date.now() - start, {
       ERROR: message,
@@ -338,7 +335,6 @@ async function fetchApplicationInfo(token: string): Promise<AppInfo> {
       team?: unknown;
       message?: string;
     };
-    const elapsedS = Math.round((Date.now() - start) / 1000);
     if (!res.ok || !data.id || !data.verify_key) {
       const reason = data.message ?? `HTTP ${res.status}`;
       s.stop(`Couldn't read application info: ${reason}`, 1);
@@ -351,7 +347,7 @@ async function fetchApplicationInfo(token: string): Promise<AppInfo> {
         'Re-run setup. If it keeps failing, check the bot token has the right scopes.',
       );
     }
-    s.stop(`Got your application details. ${k.dim(`(${elapsedS}s)`)}`);
+    s.stop(`Got your application details. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`);
     // owner is populated for solo applications; team-owned apps return a
     // team object instead and we'll fall back to a manual user-id prompt.
     const owner =
@@ -369,8 +365,7 @@ async function fetchApplicationInfo(token: string): Promise<AppInfo> {
       owner,
     };
   } catch (err) {
-    const elapsedS = Math.round((Date.now() - start) / 1000);
-    s.stop(`Couldn't reach Discord. ${k.dim(`(${elapsedS}s)`)}`, 1);
+    s.stop(`Couldn't reach Discord. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`, 1);
     const message = err instanceof Error ? err.message : String(err);
     setupLog.step('discord-app-info', 'failed', Date.now() - start, {
       ERROR: message,
@@ -399,7 +394,7 @@ async function resolveOwnerUserId(
     }
   } else {
     p.log.info(
-      "Your bot is owned by a Developer Team, so we need your Discord user ID directly.",
+      brandBody("Your bot is owned by a Developer Team, so we need your Discord user ID directly."),
     );
   }
   return await promptForUserIdWithDevMode();
@@ -450,9 +445,8 @@ async function promptInviteBot(
       '',
       '  1. Pick any server you\'re in (a personal one is fine)',
       '  2. Click "Authorize"',
-      '',
-      k.dim(url),
-    ].join('\n'),
+      formatNoteLink(url),
+    ].filter((line): line is string => line !== null).join('\n'),
     'Add bot to a server',
   );
   await confirmThenOpen(url, 'Press Enter to open the invite page');
@@ -479,7 +473,6 @@ async function openDmChannel(token: string, userId: string): Promise<string> {
       body: JSON.stringify({ recipient_id: userId }),
     });
     const data = (await res.json()) as { id?: string; message?: string };
-    const elapsedS = Math.round((Date.now() - start) / 1000);
     if (!res.ok || !data.id) {
       const reason = data.message ?? `HTTP ${res.status}`;
       s.stop(`Couldn't open a DM channel: ${reason}`, 1);
@@ -492,14 +485,13 @@ async function openDmChannel(token: string, userId: string): Promise<string> {
         'Make sure the bot is in a server you\'re also in, then retry setup.',
       );
     }
-    s.stop(`DM channel ready. ${k.dim(`(${elapsedS}s)`)}`);
+    s.stop(`DM channel ready. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`);
     setupLog.step('discord-open-dm', 'success', Date.now() - start, {
       DM_CHANNEL_ID: data.id,
     });
     return data.id;
   } catch (err) {
-    const elapsedS = Math.round((Date.now() - start) / 1000);
-    s.stop(`Couldn't reach Discord. ${k.dim(`(${elapsedS}s)`)}`, 1);
+    s.stop(`Couldn't reach Discord. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`, 1);
     const message = err instanceof Error ? err.message : String(err);
     setupLog.step('discord-open-dm', 'failed', Date.now() - start, {
       ERROR: message,
@@ -520,7 +512,7 @@ async function resolveAgentName(): Promise<string> {
   }
   const answer = ensureAnswer(
     await p.text({
-      message: 'What should your assistant be called?',
+      message: `What should your ${accentGreen('assistant')} be called?`,
       placeholder: DEFAULT_AGENT_NAME,
       defaultValue: DEFAULT_AGENT_NAME,
     }),

setup/channels/imessage.ts

@@ -36,7 +36,8 @@ import * as setupLog from '../logs.js';
 import { brightSelect } from '../lib/bright-select.js';
 import { askOperatorRole } from '../lib/role-prompt.js';
 import { ensureAnswer, fail, runQuietChild } from '../lib/runner.js';
-import { note, wrapForGutter } from '../lib/theme.js';
+import { accentGreen, note, wrapForGutter } from '../lib/theme.js';
+import { readEnvKey } from '../environment.js';
 
 const DEFAULT_AGENT_NAME = 'Nano';
 
@@ -222,8 +223,8 @@ async function walkThroughFullDiskAccess(): Promise<void> {
 }
 
 async function collectRemoteCreds(): Promise<RemoteCreds> {
-  const existingUrl = process.env.IMESSAGE_SERVER_URL?.trim();
-  const existingKey = process.env.IMESSAGE_API_KEY?.trim();
+  const existingUrl = readEnvKey('IMESSAGE_SERVER_URL');
+  const existingKey = readEnvKey('IMESSAGE_API_KEY');
   if (existingUrl && existingKey && /^https?:\/\//i.test(existingUrl)) {
     const reuse = ensureAnswer(await p.confirm({
       message: `Found existing Photon credentials (${existingUrl}). Use them?`,
@@ -317,7 +318,7 @@ async function resolveAgentName(): Promise<string> {
   }
   const answer = ensureAnswer(
     await p.text({
-      message: 'What should your assistant be called?',
+      message: `What should your ${accentGreen('assistant')} be called?`,
       placeholder: DEFAULT_AGENT_NAME,
       defaultValue: DEFAULT_AGENT_NAME,
     }),

setup/channels/signal.ts

@@ -44,7 +44,7 @@ import {
   writeStepEntry,
 } from '../lib/runner.js';
 import { askOperatorRole } from '../lib/role-prompt.js';
-import { note } from '../lib/theme.js';
+import { accentGreen, fmtDuration, note } from '../lib/theme.js';
 
 const DEFAULT_AGENT_NAME = 'Nano';
 
@@ -324,8 +324,7 @@ async function restartService(): Promise<void> {
     // Give the adapter a moment to connect to signal-cli before
     // init-first-agent's welcome DM hits the delivery path.
     await new Promise((r) => setTimeout(r, 5000));
-    const elapsed = Math.round((Date.now() - start) / 1000);
-    s.stop(`NanoClaw restarted. ${k.dim(`(${elapsed}s)`)}`);
+    s.stop(`NanoClaw restarted. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`);
     setupLog.step('signal-restart', 'success', Date.now() - start, {
       PLATFORM: platform,
     });
@@ -347,7 +346,7 @@ async function resolveAgentName(): Promise<string> {
   }
   const answer = ensureAnswer(
     await p.text({
-      message: 'What should your assistant be called?',
+      message: `What should your ${accentGreen('assistant')} be called?`,
       placeholder: DEFAULT_AGENT_NAME,
       defaultValue: DEFAULT_AGENT_NAME,
     }),

setup/channels/slack.ts

@@ -25,10 +25,11 @@ import * as p from '@clack/prompts';
 import k from 'kleur';
 
 import * as setupLog from '../logs.js';
-import { confirmThenOpen } from '../lib/browser.js';
+import { confirmThenOpen, formatNoteLink } from '../lib/browser.js';
 import { askOperatorRole } from '../lib/role-prompt.js';
 import { ensureAnswer, fail, runQuietChild } from '../lib/runner.js';
-import { note, wrapForGutter } from '../lib/theme.js';
+import { readEnvKey } from '../environment.js';
+import { accentGreen, fmtDuration, note, wrapForGutter } from '../lib/theme.js';
 
 const SLACK_API = 'https://slack.com/api';
 const SLACK_APPS_URL = 'https://api.slack.com/apps';
@@ -135,9 +136,8 @@ async function walkThroughAppCreation(): Promise<void> {
       '     slash commands and messages from the messages tab"',
       '  4. Basic Information → copy the "Signing Secret"',
       '  5. Install to Workspace → copy the "Bot User OAuth Token" (xoxb-…)',
-      '',
-      k.dim(SLACK_APPS_URL),
-    ].join('\n'),
+      formatNoteLink(SLACK_APPS_URL),
+    ].filter((line): line is string => line !== null).join('\n'),
     'Create a Slack app',
   );
   await confirmThenOpen(SLACK_APPS_URL, 'Press Enter to open Slack app settings');
@@ -151,7 +151,7 @@ async function walkThroughAppCreation(): Promise<void> {
 }
 
 async function collectBotToken(): Promise<string> {
-  const existing = process.env.SLACK_BOT_TOKEN?.trim();
+  const existing = readEnvKey('SLACK_BOT_TOKEN');
   if (existing && existing.startsWith('xoxb-') && existing.length >= 24) {
     const reuse = ensureAnswer(await p.confirm({
       message: `Found an existing Slack bot token (${existing.slice(0, 10)}…). Use it?`,
@@ -185,7 +185,7 @@ async function collectBotToken(): Promise<string> {
 }
 
 async function collectSigningSecret(): Promise<string> {
-  const existing = process.env.SLACK_SIGNING_SECRET?.trim();
+  const existing = readEnvKey('SLACK_SIGNING_SECRET');
   if (existing && /^[a-f0-9]{16,}$/i.test(existing)) {
     const reuse = ensureAnswer(await p.confirm({
       message: 'Found an existing Slack signing secret. Use it?',
@@ -241,10 +241,9 @@ async function validateSlackToken(token: string): Promise<WorkspaceInfo> {
       user_id?: string;
       error?: string;
     };
-    const elapsedS = Math.round((Date.now() - start) / 1000);
     if (data.ok && data.team && data.user) {
       s.stop(
-        `Connected to ${data.team} as @${data.user}. ${k.dim(`(${elapsedS}s)`)}`,
+        `Connected to ${data.team} as @${data.user}. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`,
       );
       const info: WorkspaceInfo = {
         teamName: data.team,
@@ -273,8 +272,7 @@ async function validateSlackToken(token: string): Promise<WorkspaceInfo> {
         : `Slack said "${reason}". Check the token scopes and workspace install, then retry.`,
     );
   } catch (err) {
-    const elapsedS = Math.round((Date.now() - start) / 1000);
-    s.stop(`Couldn't reach Slack. ${k.dim(`(${elapsedS}s)`)}`, 1);
+    s.stop(`Couldn't reach Slack. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`, 1);
     const message = err instanceof Error ? err.message : String(err);
     setupLog.step('slack-validate', 'failed', Date.now() - start, {
       ERROR: message,
@@ -334,9 +332,8 @@ async function openDmChannel(token: string, userId: string): Promise<string> {
       channel?: { id?: string };
       error?: string;
     };
-    const elapsedS = Math.round((Date.now() - start) / 1000);
     if (data.ok && data.channel?.id) {
-      s.stop(`DM channel ready. ${k.dim(`(${elapsedS}s)`)}`);
+      s.stop(`DM channel ready. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`);
       setupLog.step('slack-open-dm', 'success', Date.now() - start, {
         DM_CHANNEL_ID: data.channel.id,
       });
@@ -360,8 +357,7 @@ async function openDmChannel(token: string, userId: string): Promise<string> {
       `Slack said "${reason}". Check the member ID and app permissions, then retry.`,
     );
   } catch (err) {
-    const elapsedS = Math.round((Date.now() - start) / 1000);
-    s.stop(`Couldn't reach Slack. ${k.dim(`(${elapsedS}s)`)}`, 1);
+    s.stop(`Couldn't reach Slack. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`, 1);
     const message = err instanceof Error ? err.message : String(err);
     setupLog.step('slack-open-dm', 'failed', Date.now() - start, {
       ERROR: message,
@@ -382,7 +378,7 @@ async function resolveAgentName(): Promise<string> {
   }
   const answer = ensureAnswer(
     await p.text({
-      message: 'What should your assistant be called?',
+      message: `What should your ${accentGreen('assistant')} be called?`,
       placeholder: DEFAULT_AGENT_NAME,
       defaultValue: DEFAULT_AGENT_NAME,
     }),

setup/channels/teams.ts

@@ -42,6 +42,7 @@ import { ensureAnswer, fail, runQuietChild } from '../lib/runner.js';
 import { buildTeamsAppPackage } from '../lib/teams-manifest.js';
 import { note } from '../lib/theme.js';
 import * as setupLog from '../logs.js';
+import { readEnvKey } from '../environment.js';
 
 const CHANNEL = 'teams';
 const MANIFEST_DIR = path.join(process.cwd(), 'data', 'teams');
@@ -60,8 +61,8 @@ export async function runTeamsChannel(_displayName: string): Promise<void> {
   const collected: Collected = {};
   const completed: string[] = [];
 
-  const existingAppId = process.env.TEAMS_APP_ID?.trim();
-  const existingPassword = process.env.TEAMS_APP_PASSWORD?.trim();
+  const existingAppId = readEnvKey('TEAMS_APP_ID');
+  const existingPassword = readEnvKey('TEAMS_APP_PASSWORD');
   if (existingAppId && existingPassword) {
     const reuse = ensureAnswer(await p.confirm({
       message: `Found existing Teams credentials (App ID: ${existingAppId.slice(0, 8)}…). Use them?`,
@@ -70,9 +71,9 @@ export async function runTeamsChannel(_displayName: string): Promise<void> {
     if (reuse) {
       collected.appId = existingAppId;
       collected.appPassword = existingPassword;
-      collected.appType = (process.env.TEAMS_APP_TYPE?.trim() as 'SingleTenant' | 'MultiTenant') || 'MultiTenant';
+      collected.appType = (readEnvKey('TEAMS_APP_TYPE') as 'SingleTenant' | 'MultiTenant') || 'MultiTenant';
       if (collected.appType === 'SingleTenant') {
-        collected.tenantId = process.env.TEAMS_APP_TENANT_ID?.trim();
+        collected.tenantId = readEnvKey('TEAMS_APP_TENANT_ID') ?? undefined;
       }
       setupLog.userInput('teams_credentials', 'reused-existing');
       await installAdapter(collected);

setup/channels/telegram.ts

@@ -21,7 +21,7 @@ import * as p from '@clack/prompts';
 import k from 'kleur';
 
 import * as setupLog from '../logs.js';
-import { confirmThenOpen } from '../lib/browser.js';
+import { confirmThenOpen, formatNoteLink } from '../lib/browser.js';
 import { askOperatorRole } from '../lib/role-prompt.js';
 import {
   type Block,
@@ -33,7 +33,8 @@ import {
   spawnStep,
   writeStepEntry,
 } from '../lib/runner.js';
-import { brandBold, note } from '../lib/theme.js';
+import { readEnvKey } from '../environment.js';
+import { accentGreen, brandBold, fitToWidth, fmtDuration, note } from '../lib/theme.js';
 
 const DEFAULT_AGENT_NAME = 'Nano';
 
@@ -50,9 +51,8 @@ export async function runTelegramChannel(displayName: string): Promise<void> {
   note(
     [
       `Opening @${botUsername} in Telegram so it's ready when the pairing code shows up.`,
-      '',
-      k.dim(botUrl),
-    ].join('\n'),
+      formatNoteLink(botUrl),
+    ].filter((line): line is string => line !== null).join('\n'),
     'Open Telegram',
   );
   await confirmThenOpen(botUrl, 'Press Enter to open Telegram');
@@ -132,7 +132,7 @@ export async function runTelegramChannel(displayName: string): Promise<void> {
 }
 
 async function collectTelegramToken(): Promise<string> {
-  const existing = process.env.TELEGRAM_BOT_TOKEN?.trim();
+  const existing = readEnvKey('TELEGRAM_BOT_TOKEN');
   if (existing && /^[0-9]+:[A-Za-z0-9_-]{35,}$/.test(existing)) {
     const reuse = ensureAnswer(await p.confirm({
       message: `Found an existing Telegram bot token (${existing.slice(0, 8)}…). Use it?`,
@@ -191,10 +191,9 @@ async function validateTelegramToken(token: string): Promise<string> {
       result?: { username?: string; id?: number };
       description?: string;
     };
-    const elapsedS = Math.round((Date.now() - start) / 1000);
     if (data.ok && data.result?.username) {
       const username = data.result.username;
-      s.stop(`Found your bot: @${username}. ${k.dim(`(${elapsedS}s)`)}`);
+      s.stop(`Found your bot: @${username}. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`);
       setupLog.step('telegram-validate', 'success', Date.now() - start, {
         BOT_USERNAME: username,
         BOT_ID: data.result.id ?? '',
@@ -212,8 +211,7 @@ async function validateTelegramToken(token: string): Promise<string> {
       'Copy the token again from @BotFather and try setup once more.',
     );
   } catch (err) {
-    const elapsedS = Math.round((Date.now() - start) / 1000);
-    s.stop(`Couldn't reach Telegram. ${k.dim(`(${elapsedS}s)`)}`, 1);
+    s.stop(`Couldn't reach Telegram. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`, 1);
     const message = err instanceof Error ? err.message : String(err);
     setupLog.step('telegram-validate', 'failed', Date.now() - start, {
       ERROR: message,
@@ -254,11 +252,11 @@ async function runPairTelegram(): Promise<
           stopSpinner("Old code expired. Here's a fresh one.");
         }
         note(formatCodeCard(block.fields.CODE ?? '????'), 'Secret code');
-        s.start('Waiting for you to send the code from Telegram…');
+        s.start(fitToWidth('Waiting for you to send the code from Telegram…', ''));
         spinnerActive = true;
       } else if (block.type === 'PAIR_TELEGRAM_ATTEMPT') {
         stopSpinner(`Got "${block.fields.CANDIDATE ?? '?'}", not a match.`);
-        s.start('Waiting for the correct code…');
+        s.start(fitToWidth('Waiting for the correct code…', ''));
         spinnerActive = true;
       } else if (block.type === 'PAIR_TELEGRAM') {
         if (block.fields.STATUS === 'success') {
@@ -304,7 +302,7 @@ async function resolveAgentName(): Promise<string> {
   }
   const answer = ensureAnswer(
     await p.text({
-      message: 'What should your assistant be called?',
+      message: `What should your ${accentGreen('assistant')} be called?`,
       placeholder: DEFAULT_AGENT_NAME,
       defaultValue: DEFAULT_AGENT_NAME,
     }),

setup/channels/whatsapp.ts

@@ -46,7 +46,7 @@ import {
   writeStepEntry,
 } from '../lib/runner.js';
 import { askOperatorRole } from '../lib/role-prompt.js';
-import { brandBold, note } from '../lib/theme.js';
+import { accentGreen, brandBody, brandBold, fmtDuration, note } from '../lib/theme.js';
 
 const DEFAULT_AGENT_NAME = 'Nano';
 const AUTH_CREDS_PATH = path.join(process.cwd(), 'store', 'auth', 'creds.json');
@@ -267,7 +267,7 @@ async function runWhatsAppAuth(
           if (spinnerActive) {
             stopSpinner('WhatsApp linked.');
           } else {
-            p.log.success('WhatsApp linked.');
+            p.log.success(brandBody('WhatsApp linked.'));
           }
         } else if (status === 'failed') {
           if (qrLinesPrinted > 0) {
@@ -379,8 +379,7 @@ async function restartService(): Promise<void> {
     // Give the adapter a moment to reconnect before init-first-agent's
     // welcome DM hits the delivery path.
     await new Promise((r) => setTimeout(r, 5000));
-    const elapsed = Math.round((Date.now() - start) / 1000);
-    s.stop(`NanoClaw restarted. ${k.dim(`(${elapsed}s)`)}`);
+    s.stop(`NanoClaw restarted. ${k.dim(`(${fmtDuration(Date.now() - start)})`)}`);
     setupLog.step('whatsapp-restart', 'success', Date.now() - start, {
       PLATFORM: platform,
     });
@@ -462,7 +461,7 @@ async function resolveAgentName(): Promise<string> {
   }
   const answer = ensureAnswer(
     await p.text({
-      message: 'What should your assistant be called?',
+      message: `What should your ${accentGreen('assistant')} be called?`,
       placeholder: DEFAULT_AGENT_NAME,
       defaultValue: DEFAULT_AGENT_NAME,
     }),

setup/environment.ts

@@ -11,6 +11,30 @@ import { log } from '../src/log.js';
 import { commandExists, getPlatform, isHeadless, isWSL } from './platform.js';
 import { emitStatus } from './status.js';
 
+/**
+ * Read a single key from `.env` on disk (not process.env).
+ * Returns the trimmed value or null if the key isn't set / file doesn't exist.
+ */
+export function readEnvKey(key: string, projectRoot?: string): string | null {
+  const envPath = path.join(projectRoot ?? process.cwd(), '.env');
+  let content: string;
+  try {
+    content = fs.readFileSync(envPath, 'utf-8');
+  } catch {
+    return null;
+  }
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq < 1) continue;
+    if (trimmed.slice(0, eq) === key) {
+      return trimmed.slice(eq + 1).trim() || null;
+    }
+  }
+  return null;
+}
+
 export function detectExistingDisplayName(projectRoot: string): string | null {
   const dbPath = path.join(projectRoot, 'data', 'v2.db');
   if (!fs.existsSync(dbPath)) return null;

setup/lib/bright-select.ts

@@ -18,6 +18,8 @@ import { SelectPrompt } from '@clack/core';
 import { isCancel } from '@clack/prompts';
 import { styleText } from 'node:util';
 
+import { brandBody } from './theme.js';
+
 const BULLET_ACTIVE = '●';
 const BULLET_INACTIVE = '○';
 const BAR = '│';
@@ -95,7 +97,7 @@ export function brightSelect<T>(
         const shown =
           st === 'cancel'
             ? styleText(['strikethrough', 'dim'], selected)
-            : styleText('dim', selected);
+            : styleText('dim', brandBody(selected));
         lines.push(`${grayBar}  ${shown}`);
         return lines.join('\n');
       }
@@ -104,11 +106,12 @@ export function brightSelect<T>(
       options.forEach((opt, idx) => {
         const label = opt.label ?? String(opt.value);
         const hint = opt.hint ? ` ${styleText('dim', `(${opt.hint})`)}` : '';
-        const marker =
-          idx === cursor
-            ? styleText('green', BULLET_ACTIVE)
-            : styleText('dim', BULLET_INACTIVE);
-        lines.push(`${bar}  ${marker} ${label}${hint}`);
+        const isActive = idx === cursor;
+        const marker = isActive
+          ? styleText('green', BULLET_ACTIVE)
+          : styleText('dim', BULLET_INACTIVE);
+        const shownLabel = isActive ? brandBody(label) : label;
+        lines.push(`${bar}  ${marker} ${shownLabel}${hint}`);
       });
       lines.push(styleText(color, CAP_BOT));
       return lines.join('\n');

setup/lib/browser.ts

@@ -9,12 +9,19 @@
  * `confirmThenOpen` pauses for the operator before triggering the open —
  * the browser tends to steal focus when it pops, and a split-second
  * "wait what just happened" moment is worse than letting the user hit
- * Enter when they're ready.
+ * Enter when they're ready. On headless devices (no graphical session
+ * available) it skips both the prompt and the open: there's no browser
+ * to launch, the surrounding `note(...)` already shows the URL for
+ * copy-paste on another device, and the next prompt in the channel
+ * flow ("Got your bot token?" etc.) provides the natural completion
+ * confirmation.
  */
 import { spawn } from 'child_process';
 
 import * as p from '@clack/prompts';
+import k from 'kleur';
 
+import { isHeadless } from '../platform.js';
 import { ensureAnswer } from './runner.js';
 
 /** Best-effort open of a URL in the user's default browser. Silent on failure. */
@@ -32,18 +39,43 @@ export function openUrl(url: string): void {
   }
 }
 
+/**
+ * Format a URL for inclusion in a setup `note(...)` card. On
+ * headless devices we surface the URL inside the card with a
+ * "Get started:" label at full strength — copy-pasting onto
+ * another device is the actual action, not an incidental
+ * reference. The leading `\n` acts as a visual separator from
+ * the body steps above; callers `.filter(line => line !== null)`
+ * before joining, so on GUI we drop the line entirely (and the
+ * URL ends up below the next-step confirm prompt as a "if
+ * browser does not appear, please visit" fallback — see
+ * `confirmThenOpen`).
+ */
+export function formatNoteLink(url: string): string | null {
+  if (isHeadless()) return `\nGet started: ${url}`;
+  return null;
+}
+
 /**
  * Gate a browser-open on a confirm so the user is ready for their browser
- * to take focus. Proceeds on cancel as well — the user can always copy the
- * URL from the note that precedes the prompt.
+ * to take focus. Proceeds on cancel as well. On headless devices both the
+ * prompt and the open are skipped — the URL is already surfaced inside
+ * the surrounding note (via `formatNoteLink`).
+ *
+ * On GUI devices the confirm message includes the fallback URL on the
+ * lines below the action ("If browser does not appear, please visit:
+ * <url>" in dim) so the user has a copy-paste path right next to the
+ * action button without needing to scroll back up to the card.
  */
 export async function confirmThenOpen(
   url: string,
   message = 'Press Enter to open your browser',
 ): Promise<void> {
+  if (isHeadless()) return;
+  const fallback = `\n${k.dim(`If browser does not appear, please visit: ${url}`)}`;
   ensureAnswer(
     await p.confirm({
-      message,
+      message: `${message}${fallback}`,
       initialValue: true,
     }),
   );

setup/lib/claude-assist.ts

@@ -28,7 +28,7 @@ import * as p from '@clack/prompts';
 import k from 'kleur';
 
 import { ensureAnswer } from './runner.js';
-import { fitToWidth, note } from './theme.js';
+import { brandBody, fitToWidth, fmtDuration, note } from './theme.js';
 
 export interface AssistContext {
   stepName: string;
@@ -110,7 +110,7 @@ export async function offerClaudeAssist(
 
   const parsed = parseResponse(response);
   if (!parsed) {
-    p.log.warn("Claude responded but I couldn't parse a command out of it.");
+    p.log.warn(brandBody("Claude responded but I couldn't parse a command out of it."));
     p.log.message(k.dim(response.trim().slice(0, 500)));
     return false;
   }
@@ -295,9 +295,8 @@ async function queryClaudeUnderSpinner(
     // Move cursor back to the start of the block (WINDOW_SIZE + 1 = header + window).
     out.write(`\x1b[${WINDOW_SIZE + 1}A`);
 
-    const elapsed = Math.round((Date.now() - start) / 1000);
     const icon = SPINNER_FRAMES[frameIdx % SPINNER_FRAMES.length];
-    const suffix = ` (${elapsed}s)`;
+    const suffix = ` (${fmtDuration(Date.now() - start)})`;
     const header = fitToWidth('Asking Claude to diagnose…', suffix);
     out.write(`\x1b[2K${k.cyan(icon)}  ${header}${k.dim(suffix)}\n`);
 
@@ -355,10 +354,9 @@ async function queryClaudeUnderSpinner(
       clearBlock();
       out.write(SHOW_CURSOR);
       process.off('exit', restoreCursorOnExit);
-      const elapsed = Math.round((Date.now() - start) / 1000);
-      const suffix = ` (${elapsed}s)`;
+      const suffix = ` (${fmtDuration(Date.now() - start)})`;
       if (kind === 'ok') {
-        p.log.success(`${fitToWidth('Claude replied.', suffix)}${k.dim(suffix)}`);
+        p.log.success(`${brandBody(fitToWidth('Claude replied.', suffix))}${k.dim(suffix)}`);
         resolve(payload);
       } else {
         p.log.error(

setup/lib/claude-handoff.ts

@@ -27,7 +27,7 @@ import { execSync, spawn } from 'child_process';
 import * as p from '@clack/prompts';
 import k from 'kleur';
 
-import { note } from './theme.js';
+import { brandBody, note } from './theme.js';
 
 export interface HandoffContext {
   /** Channel this handoff is happening in (e.g., 'teams'). */
@@ -64,7 +64,7 @@ export interface HandoffContext {
 export async function offerClaudeHandoff(ctx: HandoffContext): Promise<boolean> {
   if (!isClaudeUsable()) {
     p.log.warn(
-      "Claude isn't installed yet — can't hand you off here. Finish setup first, then retry.",
+      brandBody("Claude isn't installed yet — can't hand you off here. Finish setup first, then retry."),
     );
     return false;
   }
@@ -93,7 +93,7 @@ export async function offerClaudeHandoff(ctx: HandoffContext): Promise<boolean>
       { stdio: 'inherit' },
     );
     child.on('close', () => {
-      p.log.success("Back from Claude. Let's continue.");
+      p.log.success(brandBody("Back from Claude. Let's continue."));
       resolve(true);
     });
     child.on('error', () => {

setup/lib/runner.ts

@@ -20,7 +20,7 @@ import k from 'kleur';
 import * as setupLog from '../logs.js';
 import { offerClaudeAssist } from './claude-assist.js';
 import { emit as phEmit } from './diagnostics.js';
-import { fitToWidth } from './theme.js';
+import { brandBody, fitToWidth, fmtDuration } from './theme.js';
 
 export type Fields = Record<string, string>;
 export type Block = { type: string; fields: Fields };
@@ -307,18 +307,16 @@ async function runUnderSpinner<
 ): Promise<T> {
   const s = p.spinner();
   const start = Date.now();
-  s.start(fitToWidth(labels.running, ' (999s)'));
+  s.start(fitToWidth(labels.running, ' (99m 59s)'));
   const tick = setInterval(() => {
-    const elapsed = Math.round((Date.now() - start) / 1000);
-    const suffix = ` (${elapsed}s)`;
+    const suffix = ` (${fmtDuration(Date.now() - start)})`;
     s.message(`${fitToWidth(labels.running, suffix)}${k.dim(suffix)}`);
   }, 1000);
 
   const result = await work();
 
   clearInterval(tick);
-  const elapsed = Math.round((Date.now() - start) / 1000);
-  const suffix = ` (${elapsed}s)`;
+  const suffix = ` (${fmtDuration(Date.now() - start)})`;
   if (result.ok) {
     const isSkipped = result.terminal?.fields.STATUS === 'skipped';
     const msg = isSkipped && labels.skipped ? labels.skipped : labels.done;
@@ -390,7 +388,7 @@ export async function fail(
       const skipList = [
         ...new Set([...existingSkip, ...setupLog.completedStepNames()]),
       ].join(',');
-      p.log.step(`Retrying from ${stepName}…`);
+      p.log.step(brandBody(`Retrying from ${stepName}…`));
       const result = spawnSync('pnpm', ['--silent', 'run', 'setup:auto'], {
         stdio: 'inherit',
         env: { ...process.env, NANOCLAW_SKIP: skipList },

setup/lib/theme.ts

@@ -39,6 +39,57 @@ export function brandChip(s: string): string {
   return k.bgCyan(k.black(k.bold(s)));
 }
 
+/**
+ * Accent green (#3fba50) for emphasizing a single word inside prompt
+ * messages — currently the "you" in "What should your assistant call
+ * you?" so the operator parses at a glance who the question is about.
+ * Same TTY/NO_COLOR/truecolor gating as the rest of the palette.
+ */
+export function accentGreen(s: string): string {
+  if (!USE_ANSI) return s;
+  if (TRUECOLOR) return `\x1b[38;2;63;186;80m${s}\x1b[39m`;
+  return k.green(s);
+}
+
+/**
+ * Format an elapsed-time duration (in milliseconds) for the spinner
+ * suffixes setup writes everywhere. Sub-minute durations stay in plain
+ * seconds (`47s`); once the timer crosses 60 seconds we switch to the
+ * `Xm Ys` form (`2m 34s`) so a long step doesn't read as `247s` or
+ * similar. The format is consistent above 60s — `4m 0s` over `4m` —
+ * so live spinner output doesn't change shape at every whole minute.
+ */
+export function fmtDuration(ms: number): string {
+  const totalSec = Math.round(ms / 1000);
+  if (totalSec < 60) return `${totalSec}s`;
+  const m = Math.floor(totalSec / 60);
+  const s = totalSec % 60;
+  return `${m}m ${s}s`;
+}
+
+/**
+ * Brand body color for setup-flow prose. Used for card bodies (via the
+ * `note()` formatter) and `p.log.*` body arguments — anywhere the
+ * previous "dim" treatment was making prose hard to read or washing
+ * out embedded brand emphasis.
+ *
+ * Multi-line input is colored line-by-line so embedded line breaks
+ * don't bleed the SGR sequence across clack's gutter prefix.
+ */
+export function brandBody(s: string): string {
+  if (!USE_ANSI) return s;
+  if (TRUECOLOR) {
+    return s
+      .split('\n')
+      .map((line) => (line.length > 0 ? `\x1b[38;2;43;183;206m${line}\x1b[39m` : line))
+      .join('\n');
+  }
+  return s
+    .split('\n')
+    .map((line) => (line.length > 0 ? k.cyan(line) : line))
+    .join('\n');
+}
+
 /**
  * Wrap text so it fits inside clack's gutter without the terminal's soft
  * wrap breaking the `│ …` bar on long lines. Works on a single string with
@@ -70,16 +121,13 @@ export function dimWrap(text: string, gutter: number): string {
 }
 
 /**
- * Wrap clack's `p.note` with the dim formatter disabled. By default
- * clack renders note bodies through `styleText("dim", …)`, which the
- * project's prose-readability stance (see `dimWrap` above) explicitly
- * rejects. Pass-through formatter keeps body text at the terminal's
- * regular weight; pre-styled segments (chips, bold, brand color) come
- * through unfaded.
+ * Wrap clack's `p.note` so card bodies render in the brand body color
+ * (#2b6fdc) instead of clack's default dim. Clack runs the formatter
+ * on each line individually, so `brandBody` colors each line cleanly
+ * without bleeding across the gutter prefix.
  */
-const passthroughFormat = (s: string): string => s;
 export function note(message: string, title?: string): void {
-  p.note(message, title, { format: passthroughFormat });
+  p.note(message, title, { format: brandBody });
 }
 
 const ANSI_RE = /\x1b\[[0-9;]*m/g;

setup/lib/tz-from-claude.ts

@@ -17,7 +17,7 @@ import * as p from '@clack/prompts';
 import k from 'kleur';
 
 import { isValidTimezone } from '../../src/timezone.js';
-import { fitToWidth } from './theme.js';
+import { fitToWidth, fmtDuration } from './theme.js';
 
 export function claudeCliAvailable(): boolean {
   try {
@@ -44,18 +44,16 @@ export async function resolveTimezoneViaClaude(
   const s = p.spinner();
   const start = Date.now();
   const label = 'Looking up that timezone…';
-  s.start(fitToWidth(label, ' (999s)'));
+  s.start(fitToWidth(label, ' (99m 59s)'));
   const tick = setInterval(() => {
-    const elapsed = Math.round((Date.now() - start) / 1000);
-    const suffix = ` (${elapsed}s)`;
+    const suffix = ` (${fmtDuration(Date.now() - start)})`;
     s.message(`${fitToWidth(label, suffix)}${k.dim(suffix)}`);
   }, 1000);
 
   const reply = await queryClaude(prompt);
 
   clearInterval(tick);
-  const elapsed = Math.round((Date.now() - start) / 1000);
-  const suffix = ` (${elapsed}s)`;
+  const suffix = ` (${fmtDuration(Date.now() - start)})`;
 
   const resolved = reply ? extractTimezone(reply) : null;
   if (resolved) {

setup/lib/windowed-runner.ts

@@ -23,7 +23,7 @@ import { emit as phEmit } from './diagnostics.js';
 import type { StepResult, SpinnerLabels } from './runner.js';
 import { dumpTranscriptOnFailure, spawnStep, writeStepEntry } from './runner.js';
 import * as setupLog from '../logs.js';
-import { fitToWidth } from './theme.js';
+import { brandBody, fitToWidth } from './theme.js';
 
 const WINDOW_SIZE = 3;
 const SPINNER_FRAMES = ['◒', '◐', '◓', '◑'];
@@ -169,7 +169,7 @@ async function runUnderWindow(
   if (result.ok) {
     const isSkipped = result.terminal?.fields.STATUS === 'skipped';
     const msg = isSkipped && labels.skipped ? labels.skipped : labels.done;
-    p.log.success(`${fitToWidth(msg, suffix)}${k.dim(suffix)}`);
+    p.log.success(`${brandBody(fitToWidth(msg, suffix))}${k.dim(suffix)}`);
   } else {
     const failMsg = labels.failed ?? labels.running.replace(/…$/, ' failed');
     p.log.error(`${fitToWidth(failMsg, suffix)}${k.dim(suffix)}`);
@@ -185,7 +185,7 @@ async function handleStall(
 ): Promise<void> {
   render.pauseRender();
   p.log.warn(
-    `This looks stuck — no output from the ${stepName} step for the last 60 seconds.`,
+    brandBody(`This looks stuck — no output from the ${stepName} step for the last 60 seconds.`),
   );
   phEmit('step_stalled', { step: stepName });
 

src/attachment-naming.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+
+import { deriveAttachmentName, extForMime } from './attachment-naming.js';
+
+describe('extForMime', () => {
+  it('returns empty for undefined / non-string / empty', () => {
+    expect(extForMime(undefined)).toBe('');
+    expect(extForMime('')).toBe('');
+    expect(extForMime({})).toBe('');
+    expect(extForMime(null)).toBe('');
+    expect(extForMime(42)).toBe('');
+  });
+
+  it('maps common MIME types to canonical extensions', () => {
+    expect(extForMime('image/jpeg')).toBe('jpg');
+    expect(extForMime('application/pdf')).toBe('pdf');
+    expect(extForMime('audio/ogg')).toBe('ogg');
+  });
+
+  it('strips parameters and is case-insensitive', () => {
+    expect(extForMime('image/JPEG; foo=bar')).toBe('jpg');
+    expect(extForMime('  Application/PDF  ')).toBe('pdf');
+    expect(extForMime('text/plain; charset=utf-8')).toBe('txt');
+  });
+
+  it('returns empty for unknown MIMEs', () => {
+    expect(extForMime('application/octet-stream')).toBe('');
+    expect(extForMime('application/x-totally-made-up')).toBe('');
+  });
+});
+
+describe('deriveAttachmentName', () => {
+  it('returns explicit name when set, no derivation', () => {
+    expect(deriveAttachmentName({ name: 'photo.jpg', mimeType: 'application/pdf' })).toBe('photo.jpg');
+  });
+
+  it('ignores empty / non-string explicit name and falls through to derivation', () => {
+    const out = deriveAttachmentName({ name: '', mimeType: 'application/pdf' });
+    expect(out).toMatch(/^attachment-\d+\.pdf$/);
+
+    const out2 = deriveAttachmentName({ name: 42, mimeType: 'application/pdf' });
+    expect(out2).toMatch(/^attachment-\d+\.pdf$/);
+  });
+
+  it('derives extension from mimeType when no name', () => {
+    expect(deriveAttachmentName({ mimeType: 'application/pdf' })).toMatch(/^attachment-\d+\.pdf$/);
+    expect(deriveAttachmentName({ mimeType: 'image/jpeg' })).toMatch(/^attachment-\d+\.jpg$/);
+  });
+
+  it('falls back to att.type when mimeType is missing (Telegram photos/stickers)', () => {
+    expect(deriveAttachmentName({ type: 'photo' })).toMatch(/^attachment-\d+\.jpg$/);
+    expect(deriveAttachmentName({ type: 'sticker' })).toMatch(/^attachment-\d+\.webp$/);
+    expect(deriveAttachmentName({ type: 'voice' })).toMatch(/^attachment-\d+\.ogg$/);
+    expect(deriveAttachmentName({ type: 'animation' })).toMatch(/^attachment-\d+\.mp4$/);
+  });
+
+  it('case-insensitive att.type lookup', () => {
+    expect(deriveAttachmentName({ type: 'PHOTO' })).toMatch(/^attachment-\d+\.jpg$/);
+  });
+
+  it('returns bare timestamp when nothing matches', () => {
+    expect(deriveAttachmentName({})).toMatch(/^attachment-\d+$/);
+    expect(deriveAttachmentName({ mimeType: 'application/octet-stream' })).toMatch(/^attachment-\d+$/);
+    expect(deriveAttachmentName({ type: 'mystery-class' })).toMatch(/^attachment-\d+$/);
+  });
+
+  it('does not crash on non-string mimeType (defensive against buggy bridges)', () => {
+    expect(() => deriveAttachmentName({ mimeType: { foo: 'bar' } })).not.toThrow();
+    expect(deriveAttachmentName({ mimeType: { foo: 'bar' } })).toMatch(/^attachment-\d+$/);
+  });
+});

src/attachment-naming.ts

@@ -0,0 +1,69 @@
+/**
+ * Derive a safe, extensioned filename for inbound attachments when the
+ * channel bridge passes data without an explicit `name`.
+ *
+ * Two-step lookup:
+ *   1. `mimeType` → extension (Discord/Slack documents, Telegram document
+ *      uploads — channels that set the MIME but not a filename).
+ *   2. `att.type` → extension (Telegram photos/stickers/voice/animations —
+ *      coarse media-class set by the chat-sdk bridge with no MIME).
+ *
+ * Output is still passed through `isSafeAttachmentName` at the call site.
+ * The maps emit static values, so no derivation path can construct a
+ * traversal payload — only an attacker-controlled `att.name` can, and that
+ * goes through the safety guard unchanged.
+ */
+
+// Map common MIME types to canonical file extensions. Without an extension,
+// agents (and humans) can't tell what kind of file landed in the inbox, and
+// tools keyed on extension (image viewers, exiftool, etc.) misbehave.
+const MIME_TO_EXT: Record<string, string> = {
+  'image/jpeg': 'jpg',
+  'image/png': 'png',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+  'image/heic': 'heic',
+  'audio/ogg': 'ogg',
+  'audio/mpeg': 'mp3',
+  'audio/wav': 'wav',
+  'audio/mp4': 'm4a',
+  'video/mp4': 'mp4',
+  'video/webm': 'webm',
+  'video/quicktime': 'mov',
+  'application/pdf': 'pdf',
+  'text/plain': 'txt',
+  'application/json': 'json',
+  'application/zip': 'zip',
+};
+
+// Fallback when `mimeType` is missing — Telegram photos and stickers arrive
+// without an explicit MIME on the attachment object. The channel bridge sets
+// `att.type` to a coarse media-class (`photo` / `sticker` / `voice` / etc.)
+// which is reliable enough to derive a canonical extension. Telegram's GIFs
+// are actually MP4, hence `animation: 'mp4'`.
+const TYPE_TO_EXT: Record<string, string> = {
+  image: 'jpg',
+  photo: 'jpg',
+  sticker: 'webp',
+  voice: 'ogg',
+  audio: 'mp3',
+  video: 'mp4',
+  animation: 'mp4',
+};
+
+export function extForMime(mime: unknown): string {
+  if (typeof mime !== 'string' || !mime) return '';
+  const clean = mime.split(';')[0].trim().toLowerCase();
+  return MIME_TO_EXT[clean] ?? '';
+}
+
+export function deriveAttachmentName(att: Record<string, unknown>): string {
+  const explicit = att.name;
+  if (typeof explicit === 'string' && explicit) return explicit;
+  let ext = extForMime(att.mimeType);
+  if (!ext && typeof att.type === 'string') {
+    ext = TYPE_TO_EXT[att.type.toLowerCase()] ?? '';
+  }
+  const ts = Date.now();
+  return ext ? `attachment-${ts}.${ext}` : `attachment-${ts}`;
+}

src/channels/adapter.ts

@@ -135,6 +135,7 @@ export interface ChannelAdapter {
   // Optional
   setTyping?(platformId: string, threadId: string | null): Promise<void>;
   syncConversations?(): Promise<ConversationInfo[]>;
+  resolveChannelName?(platformId: string): Promise<string | null>;
 
   /**
    * Subscribe the bot to a thread so follow-up messages route via the

src/container-runner.ts

@@ -58,7 +58,7 @@ const activeContainers = new Map<string, { process: ChildProcess; containerName:
  * a duplicate container against the same session directory, producing
  * racy double-replies.
  */
-const wakePromises = new Map<string, Promise<void>>();
+const wakePromises = new Map<string, Promise<boolean>>();
 
 export function getActiveContainerCount(): number {
   return activeContainers.size;
@@ -73,20 +73,32 @@ export function isContainerRunning(sessionId: string): boolean {
  * (the in-flight wake promise is reused).
  *
  * The container runs the v2 agent-runner which polls the session DB.
+ *
+ * Contract: never throws. Returns `true` on successful spawn, `false` on
+ * transient spawn failure (e.g. OneCLI gateway unreachable). Callers don't
+ * need to wrap — the inbound row stays pending and host-sweep retries on
+ * its next tick. Callers that care (e.g. the router's typing indicator)
+ * can branch on the boolean.
  */
-export function wakeContainer(session: Session): Promise<void> {
+export function wakeContainer(session: Session): Promise<boolean> {
   if (activeContainers.has(session.id)) {
     log.debug('Container already running', { sessionId: session.id });
-    return Promise.resolve();
+    return Promise.resolve(true);
   }
   const existing = wakePromises.get(session.id);
   if (existing) {
     log.debug('Container wake already in-flight — joining existing promise', { sessionId: session.id });
     return existing;
   }
-  const promise = spawnContainer(session).finally(() => {
-    wakePromises.delete(session.id);
-  });
+  const promise = spawnContainer(session)
+    .then(() => true)
+    .catch((err) => {
+      log.warn('wakeContainer failed — host-sweep will retry', { sessionId: session.id, err });
+      return false;
+    })
+    .finally(() => {
+      wakePromises.delete(session.id);
+    });
   wakePromises.set(session.id, promise);
   return promise;
 }
@@ -435,20 +447,18 @@ async function buildContainerArgs(
   }
 
   // OneCLI gateway — injects HTTPS_PROXY + certs so container API calls
-  // are routed through the agent vault for credential injection.
-  try {
-    if (agentIdentifier) {
-      await onecli.ensureAgent({ name: agentGroup.name, identifier: agentIdentifier });
-    }
-    const onecliApplied = await onecli.applyContainerConfig(args, { addHostMapping: false, agent: agentIdentifier });
-    if (onecliApplied) {
-      log.info('OneCLI gateway applied', { containerName });
-    } else {
-      log.warn('OneCLI gateway not applied — container will have no credentials', { containerName });
-    }
-  } catch (err) {
-    log.warn('OneCLI gateway error — container will have no credentials', { containerName, err });
+  // are routed through the agent vault for credential injection. Treated as
+  // a transient hard failure: if we can't wire the gateway, we don't spawn.
+  // The caller (router or host-sweep) catches the throw, leaves the inbound
+  // message pending, and the next sweep tick retries.
+  if (agentIdentifier) {
+    await onecli.ensureAgent({ name: agentGroup.name, identifier: agentIdentifier });
   }
+  const onecliApplied = await onecli.applyContainerConfig(args, { addHostMapping: false, agent: agentIdentifier });
+  if (!onecliApplied) {
+    throw new Error('OneCLI gateway not applied — refusing to spawn container without credentials');
+  }
+  log.info('OneCLI gateway applied', { containerName });
 
   // Host gateway
   args.push(...hostGatewayArgs());

src/host-sweep.ts

@@ -168,6 +168,8 @@ async function sweepSession(session: Session): Promise<void> {
     const dueCount = countDueMessages(inDb);
     if (dueCount > 0 && !isContainerRunning(session.id)) {
       log.info('Waking container for due messages', { sessionId: session.id, count: dueCount });
+      // wakeContainer never throws — transient spawn failures (OneCLI down,
+      // etc.) return false and leave messages pending for the next tick.
       await wakeContainer(session);
     }
 

src/modules/permissions/channel-approval.test.ts

@@ -153,8 +153,10 @@ describe('unknown-channel registration flow', () => {
     expect(kind).toBe('chat-sdk');
     const payload = JSON.parse(content as string);
     expect(payload.type).toBe('ask_question');
-    // Card names the target agent so the owner knows what they're wiring to.
-    expect(payload.question).toContain('Andy');
+    // Single-agent card offers a direct "Connect to <name>" button.
+    const connectOption = payload.options.find((o: { value: string }) => o.value.startsWith('connect:'));
+    expect(connectOption).toBeDefined();
+    expect(connectOption.label).toContain('Andy');
 
     const { getDb } = await import('../../db/connection.js');
     const rows = getDb().prepare('SELECT * FROM pending_channel_approvals').all() as Array<{
@@ -202,11 +204,11 @@ describe('unknown-channel registration flow', () => {
     };
     expect(pending).toBeDefined();
 
-    // Owner clicks approve.
+    // Owner clicks "Connect to Andy" (single-agent card).
     for (const handler of getResponseHandlers()) {
       const claimed = await handler({
         questionId: pending.messaging_group_id,
-        value: 'approve',
+        value: 'connect:ag-1',
         userId: 'owner', // raw platform id — handler namespaces it
         channelType: 'telegram',
         platformId: 'dm-owner',
@@ -215,7 +217,7 @@ describe('unknown-channel registration flow', () => {
       if (claimed) break;
     }
 
-    // Wiring created with MVP defaults.
+    // Wiring created with defaults.
     const mga = getDb()
       .prepare('SELECT * FROM messaging_group_agents WHERE messaging_group_id = ?')
       .get(pending.messaging_group_id) as {
@@ -261,7 +263,7 @@ describe('unknown-channel registration flow', () => {
     for (const handler of getResponseHandlers()) {
       const claimed = await handler({
         questionId: pending.messaging_group_id,
-        value: 'approve',
+        value: 'connect:ag-1',
         userId: 'owner',
         channelType: 'telegram',
         platformId: 'dm-owner',

src/modules/permissions/channel-approval.ts

@@ -5,24 +5,32 @@
  * addressed to the bot (SDK-confirmed mention or DM), it calls
  * `requestChannelApproval` instead of silently dropping. The flow:
  *
- *   1. Pick the target agent group we'd wire to (MVP: first by name).
- *      Multi-agent picker is a follow-up — see ACTION-ITEMS.
+ *   1. Gather all existing agent groups.
  *   2. Pick an eligible approver (owner / admin) and a reachable DM for
  *      them, reusing the same primitives the sender-approval flow uses.
- *   3. Deliver an Approve / Ignore card that names the target agent
- *      explicitly so the owner knows what they're wiring to.
+ *   3. Deliver a card with three action families:
+ *        a. Connect to [agent] — one button per existing agent group.
+ *           Single-agent installs get a one-click connect.
+ *        b. Connect new agent — prompts for a free-text name, creates
+ *           the agent immediately on reply.
+ *        c. Reject — deny the channel.
  *   4. Record a `pending_channel_approvals` row holding the original event
- *      so it can be re-routed on approve.
+ *      so it can be re-routed on connect/create.
  *
- * On approve (handler in index.ts):
- *   - Create `messaging_group_agents` with MVP defaults
+ * On connect (handler in index.ts):
+ *   - Create `messaging_group_agents` with defaults
  *     (mention-sticky for groups / pattern='.' for DMs,
  *      sender_scope='known', ignored_message_policy='accumulate')
  *   - Add the triggering sender to `agent_group_members` so sender_scope
  *     doesn't bounce the replayed message into a sender-approval cascade
  *   - Delete the pending row, replay the original event
  *
- * On ignore:
+ * On connect new agent (handler in index.ts):
+ *   - Prompt for a free-text agent name via DM
+ *   - On reply: create the agent group + filesystem, then wire
+ *     and replay as above
+ *
+ * On reject:
  *   - Set `messaging_groups.denied_at = now()` so the router stops
  *     escalating on this channel until an admin explicitly re-wires
  *   - Delete the pending row
@@ -36,19 +44,81 @@
  *   - Approver has no reachable DM.
  *   - Delivery adapter missing.
  */
-import { normalizeOptions, type RawOption } from '../../channels/ask-question.js';
-import { getAllAgentGroups } from '../../db/agent-groups.js';
-import { getMessagingGroup } from '../../db/messaging-groups.js';
+import { normalizeOptions, type NormalizedOption, type RawOption } from '../../channels/ask-question.js';
+import { createAgentGroup, getAgentGroup, getAgentGroupByFolder, getAllAgentGroups } from '../../db/agent-groups.js';
+import { getChannelAdapter } from '../../channels/channel-registry.js';
+import { getMessagingGroup, updateMessagingGroup } from '../../db/messaging-groups.js';
 import { getDeliveryAdapter } from '../../delivery.js';
+import { initGroupFilesystem } from '../../group-init.js';
 import { log } from '../../log.js';
 import type { InboundEvent } from '../../channels/adapter.js';
+import type { AgentGroup } from '../../types.js';
 import { pickApprovalDelivery, pickApprover } from '../approvals/primitive.js';
 import { createPendingChannelApproval, hasInFlightChannelApproval } from './db/pending-channel-approvals.js';
 
-const APPROVAL_OPTIONS: RawOption[] = [
-  { label: 'Approve', selectedLabel: '✅ Wired', value: 'approve' },
-  { label: 'Ignore', selectedLabel: '🙅 Ignored', value: 'reject' },
-];
+// ── Value constants (response handler in index.ts parses these) ──
+
+export const CONNECT_PREFIX = 'connect:';
+export const NEW_AGENT_VALUE = 'new_agent';
+export const CHOOSE_EXISTING_VALUE = 'choose_existing';
+export const REJECT_VALUE = 'reject';
+
+// ── Utilities ──
+
+function toFolder(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'unnamed'
+  );
+}
+
+// ── Card builders ──
+
+function buildApprovalOptions(agentGroups: AgentGroup[]): RawOption[] {
+  const options: RawOption[] = [];
+  if (agentGroups.length === 1) {
+    options.push({
+      label: `Connect to ${agentGroups[0].name}`,
+      selectedLabel: `✅ Connected to ${agentGroups[0].name}`,
+      value: `${CONNECT_PREFIX}${agentGroups[0].id}`,
+    });
+  } else {
+    options.push({
+      label: 'Choose existing agent',
+      selectedLabel: '📋 Choosing…',
+      value: CHOOSE_EXISTING_VALUE,
+    });
+  }
+  options.push({
+    label: 'Connect new agent',
+    selectedLabel: '🆕 Connecting new agent…',
+    value: NEW_AGENT_VALUE,
+  });
+  options.push({
+    label: 'Reject',
+    selectedLabel: '🙅 Rejected',
+    value: REJECT_VALUE,
+  });
+  return options;
+}
+
+function buildQuestionText(
+  isGroup: boolean,
+  senderName: string | undefined,
+  channelName: string | null,
+  channelType: string,
+): string {
+  const who = senderName ?? 'Someone';
+  if (isGroup) {
+    const where = channelName ? `${channelName} on ${channelType}` : `a ${channelType} channel`;
+    return `${who} mentioned your bot in ${where}. How would you like to handle this channel?`;
+  }
+  return `${who} sent your bot a DM on ${channelType}. How would you like to handle it?`;
+}
+
+// ── Main flow ──
 
 export interface RequestChannelApprovalInput {
   messagingGroupId: string;
@@ -58,17 +128,11 @@ export interface RequestChannelApprovalInput {
 export async function requestChannelApproval(input: RequestChannelApprovalInput): Promise<void> {
   const { messagingGroupId, event } = input;
 
-  // In-flight dedup: don't spam the owner if the same unwired channel
-  // gets more mentions / DMs while a card is already pending.
   if (hasInFlightChannelApproval(messagingGroupId)) {
-    log.debug('Channel registration already in flight — dropping retry', {
-      messagingGroupId,
-    });
+    log.debug('Channel registration already in flight — dropping retry', { messagingGroupId });
     return;
   }
 
-  // MVP: pick the first agent group by name. Multi-agent systems will get
-  // a richer card later (user picks the target from a list).
   const agentGroups = getAllAgentGroups();
   if (agentGroups.length === 0) {
     log.warn('Channel registration skipped — no agent groups configured. Run /init-first-agent.', {
@@ -76,55 +140,65 @@ export async function requestChannelApproval(input: RequestChannelApprovalInput)
     });
     return;
   }
-  const target = agentGroups[0];
+  // Use first agent group for approver resolution — owners and global admins
+  // are returned regardless of which group we pass.
+  const referenceGroup = agentGroups[0];
 
-  // pickApprover takes the target agent group's id — gets scoped admins +
-  // global admins + owners. For fresh installs with only an owner, the
-  // owner is returned.
-  const approvers = pickApprover(target.id);
+  const approvers = pickApprover(referenceGroup.id);
   if (approvers.length === 0) {
     log.warn('Channel registration skipped — no owner or admin configured', {
       messagingGroupId,
-      targetAgentGroupId: target.id,
+      targetAgentGroupId: referenceGroup.id,
     });
     return;
   }
 
   const originMg = getMessagingGroup(messagingGroupId);
   const originChannelType = originMg?.channel_type ?? '';
+
+  // Resolve channel name if not yet persisted.
+  if (originMg && !originMg.name) {
+    const channelAdapter = getChannelAdapter(originChannelType);
+    if (channelAdapter?.resolveChannelName) {
+      try {
+        const name = await channelAdapter.resolveChannelName(originMg.platform_id);
+        if (name) {
+          updateMessagingGroup(originMg.id, { name });
+          originMg.name = name;
+        }
+      } catch {
+        /* non-critical */
+      }
+    }
+  }
+
   const delivery = await pickApprovalDelivery(approvers, originChannelType);
   if (!delivery) {
     log.warn('Channel registration skipped — no DM channel for any approver', {
       messagingGroupId,
-      targetAgentGroupId: target.id,
+      targetAgentGroupId: referenceGroup.id,
     });
     return;
   }
 
   const isGroup = event.message?.isGroup ?? originMg?.is_group === 1;
 
-  // Extract sender name from the event content for a human-readable card.
   let senderName: string | undefined;
   try {
     const parsed = JSON.parse(event.message.content) as Record<string, unknown>;
     senderName = (parsed.senderName ?? parsed.sender) as string | undefined;
   } catch {
-    // non-critical — fall through to generic wording
+    // non-critical
   }
 
-  const title = isGroup ? '📣 Bot mentioned in new chat' : '💬 New direct message';
-  const question = isGroup
-    ? senderName
-      ? `${senderName} mentioned your agent in a ${originChannelType} channel. Wire it to ${target.name} and let it engage?`
-      : `Your agent was mentioned in a ${originChannelType} channel. Wire it to ${target.name} and let it engage?`
-    : senderName
-      ? `${senderName} DM'd your agent on ${originChannelType}. Wire it to ${target.name} and let it respond?`
-      : `Someone DM'd your agent on ${originChannelType}. Wire it to ${target.name} and let it respond?`;
-  const options = normalizeOptions(APPROVAL_OPTIONS);
+  const channelName = originMg?.name ?? null;
+  const title = isGroup ? '📣 Bot mentioned in new channel' : '💬 New direct message';
+  const question = buildQuestionText(isGroup, senderName, channelName, originChannelType);
+  const options = normalizeOptions(buildApprovalOptions(agentGroups));
 
   createPendingChannelApproval({
     messaging_group_id: messagingGroupId,
-    agent_group_id: target.id,
+    agent_group_id: referenceGroup.id,
     original_message: JSON.stringify(event),
     approver_user_id: delivery.userId,
     created_at: new Date().toISOString(),
@@ -134,9 +208,7 @@ export async function requestChannelApproval(input: RequestChannelApprovalInput)
 
   const adapter = getDeliveryAdapter();
   if (!adapter) {
-    log.error('Channel registration row created but no delivery adapter is wired', {
-      messagingGroupId,
-    });
+    log.error('Channel registration row created but no delivery adapter is wired', { messagingGroupId });
     return;
   }
 
@@ -148,9 +220,6 @@ export async function requestChannelApproval(input: RequestChannelApprovalInput)
       'chat-sdk',
       JSON.stringify({
         type: 'ask_question',
-        // Use messaging_group_id as the questionId — it's unique per card
-        // (PK on pending table dedups) and lets the response handler look
-        // up the pending row directly without another index.
         questionId: messagingGroupId,
         title,
         question,
@@ -159,16 +228,56 @@ export async function requestChannelApproval(input: RequestChannelApprovalInput)
     );
     log.info('Channel registration card delivered', {
       messagingGroupId,
-      targetAgentGroupId: target.id,
+      agentGroupCount: agentGroups.length,
       approver: delivery.userId,
     });
   } catch (err) {
-    log.error('Channel registration card delivery failed', {
-      messagingGroupId,
-      err,
-    });
+    log.error('Channel registration card delivery failed', { messagingGroupId, err });
   }
 }
 
-export const APPROVE_VALUE = 'approve';
-export const REJECT_VALUE = 'reject';
+// ── Helpers for the response handler (index.ts) ──
+
+/**
+ * Build normalized options for the agent-selection follow-up card.
+ */
+export function buildAgentSelectionOptions(agentGroups: AgentGroup[]): NormalizedOption[] {
+  const options: RawOption[] = agentGroups.map((ag) => ({
+    label: ag.name,
+    selectedLabel: `✅ Connected to ${ag.name}`,
+    value: `${CONNECT_PREFIX}${ag.id}`,
+  }));
+  options.push({
+    label: 'Cancel',
+    selectedLabel: '🙅 Cancelled',
+    value: REJECT_VALUE,
+  });
+  return normalizeOptions(options);
+}
+
+/**
+ * Create a new agent group and initialize its filesystem. Handles
+ * folder-name collisions with numeric suffixes.
+ */
+export function createNewAgentGroup(name: string): AgentGroup {
+  let folder = toFolder(name);
+  const baseFolder = folder;
+  let suffix = 2;
+  while (getAgentGroupByFolder(folder)) {
+    folder = `${baseFolder}-${suffix}`;
+    suffix++;
+  }
+
+  const agId = `ag-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  createAgentGroup({
+    id: agId,
+    name,
+    folder,
+    agent_provider: null,
+    created_at: new Date().toISOString(),
+  });
+
+  const ag = getAgentGroup(agId)!;
+  initGroupFilesystem(ag);
+  return ag;
+}

src/modules/permissions/db/pending-channel-approvals.ts

@@ -51,6 +51,12 @@ export function hasInFlightChannelApproval(messagingGroupId: string): boolean {
   return row !== undefined;
 }
 
+export function updatePendingChannelApprovalCard(messagingGroupId: string, title: string, optionsJson: string): void {
+  getDb()
+    .prepare('UPDATE pending_channel_approvals SET title = ?, options_json = ? WHERE messaging_group_id = ?')
+    .run(title, optionsJson, messagingGroupId);
+}
+
 export function deletePendingChannelApproval(messagingGroupId: string): void {
   getDb().prepare('DELETE FROM pending_channel_approvals WHERE messaging_group_id = ?').run(messagingGroupId);
 }

src/modules/permissions/index.ts

@@ -16,27 +16,53 @@
  * access gate is not registered and core defaults to allow-all.
  */
 import { recordDroppedMessage } from '../../db/dropped-messages.js';
+import { getAgentGroup, getAllAgentGroups } from '../../db/agent-groups.js';
 import { createMessagingGroupAgent, setMessagingGroupDeniedAt } from '../../db/messaging-groups.js';
 import {
   routeInbound,
   setAccessGate,
   setChannelRequestGate,
+  setMessageInterceptor,
   setSenderResolver,
   setSenderScopeGate,
   type AccessGateResult,
 } from '../../router.js';
 import type { InboundEvent } from '../../channels/adapter.js';
 import { registerResponseHandler, type ResponsePayload } from '../../response-registry.js';
+import { getDeliveryAdapter } from '../../delivery.js';
 import { log } from '../../log.js';
 import type { MessagingGroup, MessagingGroupAgent } from '../../types.js';
 import { canAccessAgentGroup } from './access.js';
-import { requestChannelApproval } from './channel-approval.js';
+import {
+  buildAgentSelectionOptions,
+  CHOOSE_EXISTING_VALUE,
+  CONNECT_PREFIX,
+  createNewAgentGroup,
+  NEW_AGENT_VALUE,
+  REJECT_VALUE,
+  requestChannelApproval,
+} from './channel-approval.js';
 import { addMember } from './db/agent-group-members.js';
-import { deletePendingChannelApproval, getPendingChannelApproval } from './db/pending-channel-approvals.js';
+import {
+  deletePendingChannelApproval,
+  getPendingChannelApproval,
+  updatePendingChannelApprovalCard,
+} from './db/pending-channel-approvals.js';
 import { deletePendingSenderApproval, getPendingSenderApproval } from './db/pending-sender-approvals.js';
 import { hasAdminPrivilege } from './db/user-roles.js';
 import { getUser, upsertUser } from './db/users.js';
 import { requestSenderApproval } from './sender-approval.js';
+import { ensureUserDm } from './user-dm.js';
+
+// ── Free-text name input state ──
+// Tracks approvers waiting for a text reply with the agent name. Keyed by
+// namespaced userId (e.g. "slack:U0ABC"). Cleared on receipt or restart.
+interface PendingNameInput {
+  channelMgId: string;
+  dmChannelType: string;
+  dmPlatformId: string;
+}
+const awaitingNameInput = new Map<string, PendingNameInput>();
 
 function extractAndUpsertUser(event: InboundEvent): string | null {
   let content: Record<string, unknown>;
@@ -271,22 +297,17 @@ setChannelRequestGate(async (mg, event) => {
  * by messaging_group_id). If no such row, return false so downstream
  * handlers get a shot.
  *
- * Approve: create the wiring with MVP defaults (mention-sticky for
- * groups / pattern='.' for DMs; sender_scope='known';
- * ignored_message_policy='accumulate'), add the triggering sender as a
- * member so sender_scope doesn't immediately bounce them into a
- * sender-approval card, then replay the original event.
- *
- * Deny: set `messaging_groups.denied_at = now()` so future mentions on
- * this channel drop silently until an admin explicitly wires it.
+ * Value dispatch:
+ *   connect:<id>    — wire to an existing agent group, replay the message
+ *   choose_existing — send a follow-up card listing all agents
+ *   new_agent       — prompt for a free-text agent name (interceptor
+ *                     captures the reply and creates immediately)
+ *   reject          — set denied_at, delete pending row
  */
 async function handleChannelApprovalResponse(payload: ResponsePayload): Promise<boolean> {
   const row = getPendingChannelApproval(payload.questionId);
   if (!row) return false;
 
-  // Click-auth: same pattern as sender-approval (see commit 68058cb).
-  // Raw platform userId → namespace with channelType → must match the
-  // designated approver OR have admin privilege over the target agent.
   const clickerId = payload.userId ? `${payload.channelType}:${payload.userId}` : null;
   const isAuthorized =
     clickerId !== null && (clickerId === row.approver_user_id || hasAdminPrivilege(clickerId, row.agent_group_id));
@@ -296,25 +317,129 @@ async function handleChannelApprovalResponse(payload: ResponsePayload): Promise<
       clickerId,
       expectedApprover: row.approver_user_id,
     });
-    return true; // claim but take no action
+    return true;
   }
   const approverId = clickerId;
-  const approved = payload.value === 'approve';
 
-  if (!approved) {
+  // ── Reject / Cancel ──
+  if (payload.value === REJECT_VALUE) {
     setMessagingGroupDeniedAt(row.messaging_group_id, new Date().toISOString());
     deletePendingChannelApproval(row.messaging_group_id);
     log.info('Channel registration denied', {
       messagingGroupId: row.messaging_group_id,
-      agentGroupId: row.agent_group_id,
       approverId,
     });
     return true;
   }
 
-  // Rehydrate the original event to know (a) whether it was a DM or group
-  // (chooses engage_mode default), and (b) who the triggering sender was
-  // (auto-member-add so sender_scope='known' doesn't bounce the replay).
+  // ── Choose existing agent — send agent-selection follow-up card ──
+  if (payload.value === CHOOSE_EXISTING_VALUE) {
+    const approverDm = await ensureUserDm(row.approver_user_id);
+    if (!approverDm) {
+      log.error('Channel registration: no DM channel for approver', {
+        messagingGroupId: row.messaging_group_id,
+        approverUserId: row.approver_user_id,
+      });
+      return true;
+    }
+
+    const adapter = getDeliveryAdapter();
+    if (!adapter) return true;
+
+    const agentGroups = getAllAgentGroups();
+    const options = buildAgentSelectionOptions(agentGroups);
+    const title = '📋 Choose an agent';
+    updatePendingChannelApprovalCard(row.messaging_group_id, title, JSON.stringify(options));
+
+    try {
+      await adapter.deliver(
+        approverDm.channel_type,
+        approverDm.platform_id,
+        null,
+        'chat-sdk',
+        JSON.stringify({
+          type: 'ask_question',
+          questionId: row.messaging_group_id,
+          title,
+          question: 'Which agent should handle this channel?',
+          options,
+        }),
+      );
+    } catch (err) {
+      log.error('Channel registration: agent-selection card delivery failed', {
+        messagingGroupId: row.messaging_group_id,
+        err,
+      });
+    }
+    return true;
+  }
+
+  // ── Create new agent — prompt for free-text name ──
+  if (payload.value === NEW_AGENT_VALUE) {
+    const approverDm = await ensureUserDm(row.approver_user_id);
+    if (!approverDm) {
+      log.error('Channel registration: no DM channel for approver', {
+        messagingGroupId: row.messaging_group_id,
+        approverUserId: row.approver_user_id,
+      });
+      return true;
+    }
+
+    const adapter = getDeliveryAdapter();
+    if (!adapter) {
+      log.error('Channel registration: no delivery adapter for name prompt', {
+        messagingGroupId: row.messaging_group_id,
+      });
+      return true;
+    }
+
+    awaitingNameInput.set(row.approver_user_id, {
+      channelMgId: row.messaging_group_id,
+      dmChannelType: approverDm.channel_type,
+      dmPlatformId: approverDm.platform_id,
+    });
+
+    try {
+      await adapter.deliver(
+        approverDm.channel_type,
+        approverDm.platform_id,
+        null,
+        'chat-sdk',
+        JSON.stringify({ text: 'Reply with the name for your new agent:' }),
+      );
+    } catch (err) {
+      log.error('Channel registration: name prompt delivery failed', {
+        messagingGroupId: row.messaging_group_id,
+        err,
+      });
+      awaitingNameInput.delete(row.approver_user_id);
+    }
+    return true;
+  }
+
+  // ── Resolve target agent group (connect to existing or create new) ──
+  let targetAgentGroupId: string;
+
+  if (payload.value.startsWith(CONNECT_PREFIX)) {
+    targetAgentGroupId = payload.value.slice(CONNECT_PREFIX.length);
+    const ag = getAgentGroup(targetAgentGroupId);
+    if (!ag) {
+      log.error('Channel registration: target agent group no longer exists', {
+        messagingGroupId: row.messaging_group_id,
+        targetAgentGroupId,
+      });
+      deletePendingChannelApproval(row.messaging_group_id);
+      return true;
+    }
+  } else {
+    log.warn('Channel registration: unknown response value', {
+      messagingGroupId: row.messaging_group_id,
+      value: payload.value,
+    });
+    return true;
+  }
+
+  // ── Wire + replay (shared path for connect and create) ──
   let event: InboundEvent;
   try {
     event = JSON.parse(row.original_message) as InboundEvent;
@@ -327,15 +452,6 @@ async function handleChannelApprovalResponse(payload: ResponsePayload): Promise<
     return true;
   }
 
-  // Decide engage_mode from the original event. DMs (`isMention=true` &
-  // not in a group) get `pattern='.'` (always respond). Group mentions
-  // get `mention-sticky` (respond now + follow the thread).
-  //
-  // We can't read `mg.is_group` reliably here because we only auto-create
-  // the mg with `is_group=0` on first sight — the adapter hasn't told us
-  // yet whether it's actually a group. Fall back to the InboundEvent's
-  // `threadId`: a non-null threadId implies a threaded platform (Slack
-  // channel thread, Discord thread), which we treat as a group.
   const isGroup = event.threadId !== null;
   const engageMode: MessagingGroupAgent['engage_mode'] = isGroup ? 'mention-sticky' : 'pattern';
   const engagePattern = isGroup ? null : '.';
@@ -344,7 +460,7 @@ async function handleChannelApprovalResponse(payload: ResponsePayload): Promise<
   createMessagingGroupAgent({
     id: mgaId,
     messaging_group_id: row.messaging_group_id,
-    agent_group_id: row.agent_group_id,
+    agent_group_id: targetAgentGroupId,
     engage_mode: engageMode,
     engage_pattern: engagePattern,
     sender_scope: 'known',
@@ -355,28 +471,22 @@ async function handleChannelApprovalResponse(payload: ResponsePayload): Promise<
   });
   log.info('Channel registration approved — wiring created', {
     messagingGroupId: row.messaging_group_id,
-    agentGroupId: row.agent_group_id,
+    agentGroupId: targetAgentGroupId,
     mgaId,
     engageMode,
     approverId,
   });
 
-  // Auto-admit the triggering sender. Without this, the replay below
-  // would bounce through sender-approval (sender_scope='known' +
-  // sender-is-not-a-member).
   const senderUserId = extractAndUpsertUser(event);
   if (senderUserId) {
     addMember({
       user_id: senderUserId,
-      agent_group_id: row.agent_group_id,
+      agent_group_id: targetAgentGroupId,
       added_by: approverId,
       added_at: new Date().toISOString(),
     });
   }
 
-  // Clear the pending row BEFORE replay so the gate check on the second
-  // attempt sees a wired channel (agentCount > 0) and takes the fan-out
-  // path normally.
   deletePendingChannelApproval(row.messaging_group_id);
 
   try {
@@ -391,3 +501,117 @@ async function handleChannelApprovalResponse(payload: ResponsePayload): Promise<
 }
 
 registerResponseHandler(handleChannelApprovalResponse);
+
+// ── Free-text name interceptor ──
+// Captures the next DM from an approver who clicked "Create new agent",
+// creates the agent immediately, wires the channel, and replays.
+
+setMessageInterceptor(async (event: InboundEvent): Promise<boolean> => {
+  const userId = extractAndUpsertUser(event);
+  if (!userId) return false;
+
+  const pending = awaitingNameInput.get(userId);
+  if (!pending) return false;
+  if (event.channelType !== pending.dmChannelType || event.platformId !== pending.dmPlatformId) return false;
+
+  awaitingNameInput.delete(userId);
+
+  let text: string | undefined;
+  try {
+    const parsed = JSON.parse(event.message.content) as Record<string, unknown>;
+    text = (typeof parsed.text === 'string' ? parsed.text : undefined)?.trim();
+  } catch {
+    /* fall through */
+  }
+
+  if (!text) {
+    log.warn('Channel registration: empty name reply, ignoring', { userId });
+    return true;
+  }
+
+  const row = getPendingChannelApproval(pending.channelMgId);
+  if (!row) return true;
+
+  const ag = createNewAgentGroup(text);
+  log.info('Channel registration: new agent group created', {
+    messagingGroupId: row.messaging_group_id,
+    agentGroupId: ag.id,
+    agentName: ag.name,
+    folder: ag.folder,
+  });
+
+  let originalEvent: InboundEvent;
+  try {
+    originalEvent = JSON.parse(row.original_message) as InboundEvent;
+  } catch (err) {
+    log.error('Channel registration: failed to parse stored event', {
+      messagingGroupId: row.messaging_group_id,
+      err,
+    });
+    deletePendingChannelApproval(row.messaging_group_id);
+    return true;
+  }
+
+  const isGroup = originalEvent.threadId !== null;
+  const engageMode: MessagingGroupAgent['engage_mode'] = isGroup ? 'mention-sticky' : 'pattern';
+  const engagePattern = isGroup ? null : '.';
+
+  const mgaId = `mga-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  createMessagingGroupAgent({
+    id: mgaId,
+    messaging_group_id: row.messaging_group_id,
+    agent_group_id: ag.id,
+    engage_mode: engageMode,
+    engage_pattern: engagePattern,
+    sender_scope: 'known',
+    ignored_message_policy: 'accumulate',
+    session_mode: 'shared',
+    priority: 0,
+    created_at: new Date().toISOString(),
+  });
+  log.info('Channel registration approved — wiring created', {
+    messagingGroupId: row.messaging_group_id,
+    agentGroupId: ag.id,
+    mgaId,
+    engageMode,
+    approverId: userId,
+  });
+
+  const senderUserId = extractAndUpsertUser(originalEvent);
+  if (senderUserId) {
+    addMember({
+      user_id: senderUserId,
+      agent_group_id: ag.id,
+      added_by: userId,
+      added_at: new Date().toISOString(),
+    });
+  }
+
+  deletePendingChannelApproval(row.messaging_group_id);
+
+  try {
+    await routeInbound(originalEvent);
+  } catch (err) {
+    log.error('Failed to replay message after channel approval', {
+      messagingGroupId: row.messaging_group_id,
+      err,
+    });
+  }
+
+  const adapter = getDeliveryAdapter();
+  if (adapter) {
+    const dm = await ensureUserDm(row.approver_user_id);
+    if (dm) {
+      adapter
+        .deliver(
+          dm.channel_type,
+          dm.platform_id,
+          null,
+          'chat-sdk',
+          JSON.stringify({ text: `✅ Agent "${ag.name}" created and connected.` }),
+        )
+        .catch(() => {});
+    }
+  }
+  return true;
+});

src/router.ts

@@ -27,7 +27,7 @@ import {
   getMessagingGroupWithAgentCount,
 } from './db/messaging-groups.js';
 import { findSessionForAgent } from './db/sessions.js';
-import { startTypingRefresh } from './modules/typing/index.js';
+import { startTypingRefresh, stopTypingRefresh } from './modules/typing/index.js';
 import { log } from './log.js';
 import { resolveSession, writeSessionMessage, writeOutboundDirect } from './session-manager.js';
 import { wakeContainer } from './container-runner.js';
@@ -108,6 +108,20 @@ export function setSenderScopeGate(fn: SenderScopeGateFn): void {
   senderScopeGate = fn;
 }
 
+/**
+ * Message-interceptor hook. Runs at the very top of routeInbound, before
+ * messaging-group resolution. When the interceptor returns true the message
+ * is consumed and routing stops. Used by the permissions module to capture
+ * free-text replies during multi-step approval flows (e.g. agent naming).
+ */
+export type MessageInterceptorFn = (event: InboundEvent) => Promise<boolean>;
+
+let messageInterceptor: MessageInterceptorFn | null = null;
+
+export function setMessageInterceptor(fn: MessageInterceptorFn): void {
+  messageInterceptor = fn;
+}
+
 /**
  * Channel-registration hook. Runs when the router sees a mention/DM on a
  * messaging group that has no wirings AND hasn't been denied. The hook is
@@ -142,6 +156,10 @@ function safeParseContent(raw: string): { text?: string; sender?: string; sender
  * Creates messaging group + session if they don't exist yet.
  */
 export async function routeInbound(event: InboundEvent): Promise<void> {
+  // Pre-route interceptor — lets modules consume messages before any routing
+  // (e.g. free-text replies during multi-step approval flows).
+  if (messageInterceptor && (await messageInterceptor(event))) return;
+
   // 0. Apply the adapter's thread policy. Non-threaded adapters (Telegram,
   //    WhatsApp, iMessage, email) collapse threads to the channel.
   const adapter = getChannelAdapter(event.channelType);
@@ -457,7 +475,11 @@ async function deliverToAgent(
     startTypingRefresh(session.id, session.agent_group_id, event.channelType, event.platformId, event.threadId);
     const freshSession = getSession(session.id);
     if (freshSession) {
-      await wakeContainer(freshSession);
+      const woke = await wakeContainer(freshSession);
+      // wakeContainer never throws — it returns false on transient spawn
+      // failure (host-sweep retries). Stop the typing indicator we just
+      // started so it doesn't leak; the inbound row stays pending.
+      if (!woke) stopTypingRefresh(freshSession.id);
     }
   }
 }

src/session-manager.ts

@@ -14,6 +14,7 @@ import type Database from 'better-sqlite3';
 import fs from 'fs';
 import path from 'path';
 
+import { deriveAttachmentName } from './attachment-naming.js';
 import { isSafeAttachmentName } from './attachment-safety.js';
 import type { OutboundFile } from './channels/adapter.js';
 import { DATA_DIR } from './config.js';
@@ -259,7 +260,7 @@ function extractAttachmentFiles(
       // this guard, `path.join(inboxDir, '../../...')` writes anywhere the
       // host process has fs permission — see Signal Desktop's Nov 2025
       // attachment-fileName advisory for the same archetype.
-      const rawName = (att.name as string | undefined) ?? `attachment-${Date.now()}`;
+      const rawName = deriveAttachmentName(att);
       const filename = isSafeAttachmentName(rawName) ? rawName : `attachment-${Date.now()}`;
       if (filename !== rawName) {
         log.warn('Refused unsafe attachment filename — would escape inbox', {
@@ -372,6 +373,11 @@ export function readOutboxFiles(
   if (!fs.existsSync(outboxDir)) return undefined;
   const files: OutboundFile[] = [];
   for (const filename of filenames) {
+    // Reject any name that isn't a bare basename before touching the filesystem.
+    if (!isSafeAttachmentName(filename)) {
+      log.warn('Refused unsafe outbox filename — would escape outbox', { messageId, filename });
+      continue;
+    }
     const filePath = path.join(outboxDir, filename);
     if (fs.existsSync(filePath)) {
       files.push({ filename, data: fs.readFileSync(filePath) });