fix: address v0.8.6 release-review findings

Five-persona pre-release review of #886 (session traces in headless serve).
No P0/HOLD; these are the actionable polish items:

- trace-consumer.ts (flush): finalize sessions concurrently (Promise.allSettled)
  instead of sequentially. Each endTrace() can wait on an HttpExporter (5s
  timeout), so a sequential loop over N sessions could exceed a container's
  shutdown grace period and be SIGKILL'd mid-write. Now bounded to the slowest
  single trace.
- trace-consumer.ts (reconnect): log the in-process stream reconnect at debug,
  not warn — it's automatic and not user-actionable, and warn-per-backoff
  spiked log aggregators during an outage.
- serve.ts: comment clarifying that subscribeTraceConsumer's `directory` is the
  SDK workspace context, not the trace output dir (flagged by 4 reviewers).
- docs: ide.md now lists session tracing as an IDE feature; trace.md crash-
  recovery notes that `serve` (not just `run`) finalizes traces on shutdown.

Deferred (filed): #915 (container trace persistence), #916 (serve trace-dir
startup log).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: anandgupta42

docs/docs/configure/trace.md

@@ -325,7 +325,7 @@ Traces are designed to survive process crashes:
 
 2. **Incremental snapshots.** After every tool call and generation completion, the trace file is updated atomically (write to temp file, then rename). The file on disk always contains a valid, complete JSON document.
 
-3. **Crash handlers.** The `run` command registers `SIGINT`/`SIGTERM`/`beforeExit` handlers that flush the trace synchronously with a `"crashed"` status.
+3. **Crash handlers.** The `run` and `serve` commands register `SIGINT`/`SIGTERM`/`beforeExit` handlers that finalize in-flight traces on shutdown. (`run` flushes synchronously with a `"crashed"` status; `serve` drains and finalizes its active sessions.)
 
 4. **Status indicators.** Trace status tells you exactly what happened:
 

docs/docs/usage/ide.md

@@ -39,6 +39,7 @@ This opens the Altimate Code chat panel where you can interact with altimate age
 - **Tool call results inline** — SQL analysis, lineage, dbt operations, and more displayed in the chat
 - **Agent mode switching** — switch between Builder (full read/write), Analyst (read-only), and Plan (minimal access) modes from the command palette
 - **100+ data engineering tools** — SQL validation, query optimization, column lineage, dbt model generation, FinOps analysis, schema exploration, and more
+- **Session tracing** — every chat session is recorded as a trace file (the IDE panel runs `altimate-code serve` under the hood, which now writes traces just like the terminal). Inspect them with `altimate-code trace list` / `altimate-code trace view <id>`. See [Traces](../configure/trace.md).
 
 ## Configuration
 

packages/opencode/src/altimate/observability/trace-consumer.ts

@@ -309,11 +309,17 @@ export class TraceConsumer {
     this.sessionUserMsgIds.clear()
   }
 
-  /** End all in-flight traces and wait for them. Used on shutdown. */
+  /**
+   * End all in-flight traces and wait for them. Used on shutdown.
+   * Finalizes sessions concurrently rather than sequentially: each
+   * `endTrace()` can wait on an HttpExporter (5s timeout each), so a sequential
+   * loop over N sessions could take N×5s and blow past a container's shutdown
+   * grace period (e.g. k8s `terminationGracePeriodSeconds`) and be SIGKILL'd
+   * mid-write. Concurrent finalization bounds the wall-clock to the slowest
+   * single trace.
+   */
   async flush() {
-    for (const [, trace] of this.sessionTraces) {
-      await trace.endTrace().catch(() => {})
-    }
+    await Promise.allSettled([...this.sessionTraces.values()].map((trace) => trace.endTrace().catch(() => {})))
     this.sessionTraces.clear()
     this.sessionUserMsgIds.clear()
   }
@@ -410,7 +416,11 @@ export function subscribeTraceConsumer(
         }
       } catch (err) {
         if (!signal.aborted) {
-          Log.Default.warn("[tracing] trace event stream disconnected, reconnecting", {
+          // debug, not warn: this is the in-process event stream, reconnect is
+          // automatic and not user-actionable. Logging at warn on every backoff
+          // iteration (up to ~7 in the first 8s of an outage) would spike log
+          // aggregators for something the operator can't act on.
+          Log.Default.debug("[tracing] trace event stream ended, reconnecting", {
             error: err instanceof Error ? err.message : String(err),
           })
         }

packages/opencode/src/cli/cmd/serve.ts

@@ -29,6 +29,10 @@ export const ServeCommand = cmd({
     // serve mode. Subscribe the shared trace consumer to the in-process
     // event stream so serve sessions produce the same trace files as the
     // terminal entrypoints.
+    //
+    // `directory` is the SDK workspace/routing context, NOT the trace output
+    // location — trace files always go to the configured tracing dir
+    // (`tracing.dir`, default ~/.local/share/altimate-code/traces/).
     const traceSub = subscribeTraceConsumer({ directory: process.cwd() })
 
     // Finalize traces on shutdown. `serve` blocks forever on the promise below