feat(map): tidy terminal UX — suppress raw agent output, heartbeat, clean finish

`polylane map` inherited the agent's stdout, so a run dumped the agent's raw
markdown (literal **bold**, tool-call noise) into the terminal with no framing,
and showed nothing at all until the agent's final buffered response landed —
which reads as hung during a multi-minute map.

Now the agent's output is captured, not streamed: we print a short intro, a
heartbeat with elapsed time while it runs, and a clean completion line pointing
at the workspace. The captured output is surfaced only if the run fails, so a
failure is never silent. The rendered result (topology, issues, first-run
thread) lives in the workspace, not the terminal.

Note: mapping submits its topology in a single shot at the end, so there is no
per-node streaming to show here; a live phase indicator in the console is a
separate follow-up.

Part of unified onboarding (coreplanelabs/nominal#1165).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Justin Helmer

src/commands/map.ts

@@ -6,6 +6,7 @@ import type { Command } from '../command';
 import type { Config } from '../config/schema';
 import type { GlobalFlags } from '../types/flags';
 import { AGENTS, AGENT_IDS, MAPPING_PROMPT, agentById, type AgentSetup, type HeadlessRun } from '../agents/registry';
+import { consoleBaseUrl } from '../auth/oauth';
 import { isInteractive } from '../utils/env';
 import { promptSelect } from '../utils/prompt';
 import { CLIError } from '../errors/base';
@@ -47,17 +48,66 @@ export function resolveRunnable(
   return { viaSibling: false };
 }
 
-function runChild(bin: string, argv: string[], env?: Record<string, string>): Promise<number> {
+function formatElapsed(ms: number): string {
+  const total = Math.floor(ms / 1000);
+  const m = Math.floor(total / 60);
+  const s = total % 60;
+  return m > 0 ? `${m}m ${s}s` : `${s}s`;
+}
+
+/**
+ * Run the agent headlessly, capturing its output instead of streaming it. A
+ * coding agent's raw output is markdown and mostly tool calls, so dumping it
+ * into the terminal is a wall of noise; the rendered result lives in the
+ * workspace. We show a heartbeat while it runs and surface the captured log
+ * only if it fails. Returns the exit code and everything the agent printed.
+ */
+function runMapping(
+  bin: string,
+  argv: string[],
+  env: Record<string, string> | undefined,
+  onStart: () => void
+): Promise<{ code: number; output: string }> {
   return new Promise((resolve, reject) => {
     const child = spawn(bin, argv, {
-      stdio: 'inherit',
+      stdio: ['ignore', 'pipe', 'pipe'],
       cwd: process.cwd(),
       env: { ...process.env, ...(env ?? {}) },
     });
-    child.on('error', (err) =>
-      reject(new CLIError(`Failed to launch ${bin}: ${(err as Error).message}`, ExitCode.GENERAL))
-    );
-    child.on('close', (code) => resolve(code ?? 0));
+
+    // Keep at most the tail of the output so a long run can't grow unbounded;
+    // only the end matters when we surface it after a failure.
+    const MAX_CAPTURE = 64 * 1024;
+    let output = '';
+    const capture = (chunk: Buffer): void => {
+      output += chunk.toString();
+      if (output.length > MAX_CAPTURE) output = output.slice(output.length - MAX_CAPTURE);
+    };
+    child.stdout?.on('data', capture);
+    child.stderr?.on('data', capture);
+
+    onStart();
+    const started = Date.now();
+    const tty = Boolean(process.stderr.isTTY);
+    const heartbeat = setInterval(() => {
+      const elapsed = formatElapsed(Date.now() - started);
+      if (tty) process.stderr.write(`\r\x1b[2mMapping… ${elapsed} elapsed\x1b[0m\x1b[K`);
+      else process.stderr.write(`Mapping… ${elapsed} elapsed\n`);
+    }, 5000);
+
+    const finish = (): void => {
+      clearInterval(heartbeat);
+      if (tty) process.stderr.write('\r\x1b[K');
+    };
+
+    child.on('error', (err) => {
+      finish();
+      reject(new CLIError(`Failed to launch ${bin}: ${(err as Error).message}`, ExitCode.GENERAL));
+    });
+    child.on('close', (code) => {
+      finish();
+      resolve({ code: code ?? 0, output });
+    });
   });
 }
 
@@ -129,14 +179,28 @@ export const mapCommand: Command = {
       return;
     }
 
-    process.stderr.write(`Mapping this repository with ${agent.name}...\n`);
-    const code = await runChild(run.bin, argv, run.env);
+    const workspaceUrl = consoleBaseUrl(config);
+    const { code, output } = await runMapping(run.bin, argv, run.env, () => {
+      process.stderr.write(
+        `Mapping this repository with ${agent.name}. Your agent reads the repo, runs checks, and\n` +
+          `assembles the map locally; this usually takes a few minutes.\n`
+      );
+    });
+
     if (code !== 0) {
+      // Surface the tail of the captured output so a failure isn't silent.
+      const tail = output.trim().split('\n').slice(-20).join('\n');
+      if (tail) process.stderr.write(`\n${tail}\n`);
       throw new CLIError(
         `${agent.name} exited with code ${code} before finishing the map`,
         ExitCode.GENERAL,
         `Run it yourself: open ${agent.name} and ask "${MAPPING_PROMPT}"`
       );
     }
+
+    process.stderr.write(
+      `\n✓ Mapped this repository. Your topology, issues, and first-run thread are in your workspace:\n` +
+        `  ${workspaceUrl}\n`
+    );
   },
 };