noctrace 0.9.0 → 1.1.0

package/README.md

@@ -87,6 +87,7 @@ Requires Node.js 20+. Optional `--install-hooks` flag enables real-time hook eve
 - **API Error Markers** — rate limit, billing, and auth failures appear as full-width red alert banners on the timeline
 - **Agent Teams Panel** — detects running Agent Teams at `~/.claude/teams/`, shows members and task counts in a flyout
 - **Context Startup Flyout** — shows which instruction files (CLAUDE.md and others) loaded at session start with estimated token counts, parsed from JSONL system records
+- **Docker Support** — `npx noctrace --docker <container>` attaches to a running Docker container, injects a lightweight watcher, and streams JSONL events back to your host in real time. Zero container setup required
 
 ![Noctrace waterfall timeline](docs/screenshots/noctrace-waterfall.gif)
 
@@ -141,6 +142,8 @@ No config files. No cloud. Everything stays local. Optional hooks for richer rea
 
 | CLI Flag | Description |
 |----------|-------------|
+| `--docker <container>` | Attach to a running Docker container and stream its Claude Code sessions back to your host. Zero container setup |
+| `--devcontainer <path>` | Resolve the running devcontainer for a local folder path and attach to it. Pass `.` for the current directory. Falls back to `--docker` if you pass a container name directly |
 | `--install-hooks` | Configure Claude Code to push real-time events to noctrace |
 | `--uninstall-hooks` | Remove noctrace hooks from Claude Code |
 

package/bin/docker-watcher.sh

@@ -0,0 +1,108 @@
+#!/bin/sh
+# Noctrace Docker Watcher — injected into containers to stream JSONL to host.
+# Usage: docker-watcher.sh <claude_dir> <noctrace_url> <container_name>
+# Streams JSONL lines via curl POST to the noctrace /api/docker/stream endpoint.
+# Sends heartbeats every 10 seconds to /api/docker/heartbeat.
+
+CLAUDE_DIR="$1"
+NOCTRACE_URL="$2"
+CONTAINER_NAME="$3"
+PROJECTS_DIR="$CLAUDE_DIR/projects"
+
+if [ -z "$CLAUDE_DIR" ] || [ -z "$NOCTRACE_URL" ] || [ -z "$CONTAINER_NAME" ]; then
+  echo "Usage: docker-watcher.sh <claude_dir> <noctrace_url> <container_name>" >&2
+  exit 1
+fi
+
+# Track watched files to avoid duplicate tail processes
+WATCHED="/tmp/.noctrace-watched-$$"
+PIDS="/tmp/.noctrace-pids-$$"
+touch "$WATCHED" "$PIDS"
+
+cleanup() {
+  # Kill all tail processes we started
+  while IFS= read -r pid; do
+    kill "$pid" 2>/dev/null
+  done < "$PIDS"
+  rm -f "$WATCHED" "$PIDS"
+  exit 0
+}
+
+trap cleanup TERM INT
+
+# Detect HTTP client
+if command -v curl >/dev/null 2>&1; then
+  HTTP_CMD="curl"
+elif command -v wget >/dev/null 2>&1; then
+  HTTP_CMD="wget"
+else
+  echo "[noctrace-watcher] Neither curl nor wget found in container" >&2
+  exit 1
+fi
+
+post_stream() {
+  file="$1"
+  if [ "$HTTP_CMD" = "curl" ]; then
+    curl -s -X POST "$NOCTRACE_URL/api/docker/stream" \
+      -H "Content-Type: text/plain" \
+      -H "X-Container-Name: $CONTAINER_NAME" \
+      -H "X-Container-Path: $file" \
+      --data-binary @- || true
+  else
+    wget -q -O /dev/null --post-file=- \
+      --header="Content-Type: text/plain" \
+      --header="X-Container-Name: $CONTAINER_NAME" \
+      --header="X-Container-Path: $file" \
+      "$NOCTRACE_URL/api/docker/stream" 2>/dev/null || true
+  fi
+}
+
+post_heartbeat() {
+  if [ "$HTTP_CMD" = "curl" ]; then
+    curl -s -X POST "$NOCTRACE_URL/api/docker/heartbeat" \
+      -H "X-Container-Name: $CONTAINER_NAME" || true
+  else
+    wget -q -O /dev/null --post-data="" \
+      --header="X-Container-Name: $CONTAINER_NAME" \
+      "$NOCTRACE_URL/api/docker/heartbeat" 2>/dev/null || true
+  fi
+}
+
+watch_file() {
+  file="$1"
+  # Send full file content then follow new lines
+  tail -f -n +1 "$file" 2>/dev/null | while IFS= read -r line; do
+    printf '%s\n' "$line" | post_stream "$file"
+  done &
+  echo $! >> "$PIDS"
+  echo "$file" >> "$WATCHED"
+}
+
+# Initial scan — watch all existing JSONL files
+if [ -d "$PROJECTS_DIR" ]; then
+  find "$PROJECTS_DIR" -name "*.jsonl" -type f 2>/dev/null | while IFS= read -r f; do
+    watch_file "$f"
+  done
+fi
+
+# Main loop: scan for new files + send heartbeat
+HEARTBEAT_COUNTER=0
+while true; do
+  sleep 3
+
+  # Scan for new JSONL files (including subagents)
+  if [ -d "$PROJECTS_DIR" ]; then
+    find "$PROJECTS_DIR" -name "*.jsonl" -type f 2>/dev/null | while IFS= read -r f; do
+      if ! grep -qxF "$f" "$WATCHED" 2>/dev/null; then
+        watch_file "$f"
+      fi
+    done
+  fi
+
+  # Heartbeat every ~10 seconds (3s sleep * 3 iterations)
+  HEARTBEAT_COUNTER=$((HEARTBEAT_COUNTER + 1))
+  if [ "$HEARTBEAT_COUNTER" -ge 3 ]; then
+    post_heartbeat
+    HEARTBEAT_COUNTER=0
+  fi
+done

package/bin/noctrace-mcp.js

@@ -20,9 +20,14 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 
-const VERSION = '0.5.1';
-const NOCTRACE_PORT = 4117;
-const BASE_URL = `http://localhost:${NOCTRACE_PORT}`;
+const VERSION = '0.9.0';
+const NOCTRACE_PORT = parseInt(process.env.NOCTRACE_PORT ?? '4117', 10);
+
+// Validate NOCTRACE_HOST: only allow localhost, 127.0.0.1, and host.docker.internal
+const rawHost = process.env.NOCTRACE_HOST ?? 'localhost';
+const ALLOWED_HOSTS = ['localhost', '127.0.0.1', 'host.docker.internal'];
+const NOCTRACE_HOST = ALLOWED_HOSTS.includes(rawHost) ? rawHost : 'localhost';
+const BASE_URL = `http://${NOCTRACE_HOST}:${NOCTRACE_PORT}`;
 
 // ---------------------------------------------------------------------------
 // Session path discovery
@@ -71,26 +76,56 @@ async function newestJsonl(dir) {
   return newest;
 }
 
+/**
+ * Translate a container-internal path to the host-side path.
+ * Uses NOCTRACE_PATH_MAP env var: "container_prefix:host_prefix"
+ * Example: NOCTRACE_PATH_MAP="/root/.claude:/Users/lam/.claude"
+ *
+ * @param {string} containerPath
+ * @returns {string}
+ */
+function translatePath(containerPath) {
+  const pathMap = process.env.NOCTRACE_PATH_MAP;
+  if (!pathMap) return containerPath;
+  const sep = pathMap.indexOf(':');
+  if (sep === -1) return containerPath;
+  const containerPrefix = pathMap.slice(0, sep);
+  const hostPrefix = pathMap.slice(sep + 1);
+  if (containerPath.startsWith(containerPrefix)) {
+    const translated = hostPrefix + containerPath.slice(containerPrefix.length);
+    // Validate no path traversal: resolved path must stay under hostPrefix
+    const resolved = path.resolve(translated);
+    if (!resolved.startsWith(path.resolve(hostPrefix) + path.sep) && resolved !== path.resolve(hostPrefix)) {
+      process.stderr.write(`[noctrace-mcp] Path traversal blocked: ${containerPath}\n`);
+      return containerPath;
+    }
+    return translated;
+  }
+  return containerPath;
+}
+
 /**
  * Discover the JSONL session path for the current Claude Code session.
+ * Returns the host-translated path when NOCTRACE_PATH_MAP is set.
  *
  * @returns {Promise<string|null>}
  */
 async function discoverSessionPath() {
   // Option a: direct env var
   if (process.env.CLAUDE_SESSION_PATH) {
-    return process.env.CLAUDE_SESSION_PATH;
+    return translatePath(process.env.CLAUDE_SESSION_PATH);
   }
 
   // Option b: derive from project directory
   const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.env.PWD ?? null;
   if (!projectDir) return null;
 
-  const claudeHome = process.env.CLAUDE_HOME ?? path.join(os.homedir(), '.claude');
+  const claudeHome = process.env.CLAUDE_CONFIG_DIR ?? process.env.CLAUDE_HOME ?? path.join(os.homedir(), '.claude');
   const slug = pathToSlug(projectDir);
   const projectSessionDir = path.join(claudeHome, 'projects', slug);
 
-  return newestJsonl(projectSessionDir);
+  const sessionPath = await newestJsonl(projectSessionDir);
+  return sessionPath ? translatePath(sessionPath) : null;
 }
 
 // ---------------------------------------------------------------------------
@@ -149,7 +184,7 @@ async function postSessionAction(action, sessionPath) {
   return new Promise((resolve) => {
     const req = http.request(
       {
-        hostname: 'localhost',
+        hostname: NOCTRACE_HOST,
         port: NOCTRACE_PORT,
         path: `/api/sessions/${action}`,
         method: 'POST',
@@ -254,10 +289,14 @@ function handleMessage(line) {
 async function main() {
   let sessionPath = await discoverSessionPath();
 
+  // When running inside Docker (NOCTRACE_HOST != localhost), skip server start —
+  // the noctrace server runs on the host, not inside the container.
+  const isRemote = NOCTRACE_HOST !== 'localhost' && NOCTRACE_HOST !== '127.0.0.1';
+
   // Check if noctrace is already running; if not, start it (first MCP process wins).
   // Use a retry loop to handle the race where two MCP processes start simultaneously.
   const running = await isServerRunning();
-  if (!running) {
+  if (!running && !isRemote) {
     process.stderr.write('[noctrace-mcp] Starting noctrace server...\n');
     try {
       await startNoctraceServer();

package/bin/noctrace.js

@@ -197,6 +197,164 @@ if (args.includes('--disable')) {
   process.exit(0);
 }
 
+/**
+ * Run Docker watcher mode with a known, already-validated container ID.
+ * Shared by --docker and --devcontainer.
+ */
+async function runDockerMode(containerArg) {
+  const {
+    isValidContainerName,
+    assertContainerRunning,
+    resolveClaudeDir,
+    detectHttpTool,
+    resolveHostUrl,
+    copyWatcherScript,
+    spawnWatcher,
+    cleanupWatcher,
+    defaultDockerRunner,
+  } = await import('../dist/server/server/docker.js');
+
+  const { readFileSync, writeFileSync, unlinkSync } = await import('node:fs');
+
+  // Validate container name to prevent command injection
+  if (!isValidContainerName(containerArg)) {
+    console.error(`[noctrace] Invalid container name: "${containerArg}"`);
+    process.exit(1);
+  }
+
+  // Verify container exists and is running
+  try {
+    assertContainerRunning(containerArg, defaultDockerRunner);
+  } catch (err) {
+    console.error(`[noctrace] ${err.message}`);
+    process.exit(1);
+  }
+
+  // Find Claude config dir inside the container
+  const claudeDir = resolveClaudeDir(containerArg, defaultDockerRunner);
+  console.log(`[noctrace] Connecting to container "${containerArg}" (claude dir: ${claudeDir})`);
+
+  // Check if curl or wget exists in the container
+  const httpTool = detectHttpTool(containerArg, defaultDockerRunner);
+  if (httpTool === 'none') {
+    console.error('[noctrace] Container has neither curl nor wget. Cannot stream sessions.');
+    console.error('[noctrace] Install curl in the container: apt-get install -y curl');
+    process.exit(1);
+  }
+
+  // Resolve host URL that the container can reach
+  const hostUrl = resolveHostUrl(containerArg, defaultDockerRunner);
+
+  // Start noctrace server on the host
+  process.env.NOCTRACE_NO_AUTOSTART = '1';
+  process.env.NODE_ENV = 'production';
+  const { startServer } = await import('../dist/server/server/index.js');
+  const openMod = await import('open');
+  const port = await startServer();
+  const url = `http://localhost:${port}`;
+  const containerTargetUrl = `${hostUrl}:${port}`;
+  console.log(`[noctrace] Dashboard: ${url}`);
+  console.log(`[noctrace] Container will stream to: ${containerTargetUrl}`);
+  await openMod.default(url);
+
+  // Read the watcher script from the package
+  const watcherScript = readFileSync(
+    new URL('./docker-watcher.sh', import.meta.url), 'utf8'
+  );
+
+  // Copy watcher script into the container
+  console.log(`[noctrace] Injecting watcher into container...`);
+  const tmpScript = path.join(os.tmpdir(), `noctrace-watcher-${Date.now()}.sh`);
+  writeFileSync(tmpScript, watcherScript);
+
+  try {
+    copyWatcherScript(containerArg, tmpScript, defaultDockerRunner);
+  } finally {
+    unlinkSync(tmpScript);
+  }
+
+  // Run the watcher in the background inside the container
+  spawnWatcher(containerArg, claudeDir, containerTargetUrl, defaultDockerRunner);
+
+  console.log(`[noctrace] Watcher injected. Streaming sessions in real-time.`);
+  console.log(`[noctrace] Press Ctrl+C to stop.`);
+
+  // Monitor heartbeats
+  let lastHeartbeatCheck = Date.now();
+  const heartbeatInterval = setInterval(async () => {
+    try {
+      const { default: http } = await import('node:http');
+      const result = await new Promise((resolve) => {
+        const req = http.get(`http://localhost:${port}/api/docker/status`, { timeout: 2000 }, (res) => {
+          let data = '';
+          res.on('data', (chunk) => { data += chunk; });
+          res.on('end', () => { try { resolve(JSON.parse(data)); } catch { resolve(null); } });
+        });
+        req.on('error', () => resolve(null));
+      });
+
+      if (result && result.containers) {
+        const container = result.containers.find((c) => c.name === containerArg);
+        if (container && container.stale && Date.now() - lastHeartbeatCheck > 30000) {
+          console.log(`[noctrace] Warning: No heartbeat from container "${containerArg}" in 30s. It may have stopped.`);
+          lastHeartbeatCheck = Date.now();
+        }
+      }
+    } catch { /* heartbeat check is best-effort */ }
+  }, 15000);
+
+  // Cleanup on exit
+  process.on('SIGINT', () => {
+    console.log('\n[noctrace] Stopping...');
+    clearInterval(heartbeatInterval);
+    cleanupWatcher(containerArg, defaultDockerRunner);
+    console.log('[noctrace] Stopped.');
+    process.exit(0);
+  });
+  process.on('SIGTERM', () => process.exit(0));
+
+  // Keep process alive
+  await new Promise(() => {});
+}
+
+if (args.includes('--docker')) {
+  const containerArg = args[args.indexOf('--docker') + 1];
+  if (!containerArg || containerArg.startsWith('--')) {
+    console.error('[noctrace] Usage: npx noctrace --docker <container-name-or-id>');
+    console.error('[noctrace] Example: npx noctrace --docker my-claude-container');
+    process.exit(1);
+  }
+  await runDockerMode(containerArg);
+}
+
+if (args.includes('--devcontainer')) {
+  const devcontainerArg = args[args.indexOf('--devcontainer') + 1];
+  if (!devcontainerArg || devcontainerArg.startsWith('--')) {
+    console.error('[noctrace] Usage: npx noctrace --devcontainer <path-or-container>');
+    console.error('[noctrace] Examples:');
+    console.error('[noctrace]   npx noctrace --devcontainer .');
+    console.error('[noctrace]   npx noctrace --devcontainer /Users/me/myproject');
+    console.error('[noctrace]   npx noctrace --devcontainer my-devcontainer-id');
+    process.exit(1);
+  }
+
+  const { resolveDevcontainerContainer, defaultDockerRunner } =
+    await import('../dist/server/server/docker.js');
+
+  let resolvedContainer;
+  try {
+    resolvedContainer = resolveDevcontainerContainer(devcontainerArg, defaultDockerRunner);
+  } catch (err) {
+    const lines = err.message.split('\n');
+    for (const line of lines) {
+      console.error(`[noctrace] ${line}`);
+    }
+    process.exit(1);
+  }
+
+  await runDockerMode(resolvedContainer);
+}
+
 if (args.includes('--mcp')) {
   // MCP mode: boot the Express server and speak JSON-RPC over stdio.
   // stdout is the JSON-RPC channel — all logging must go to stderr.

package/dist/server/server/docker.js

@@ -0,0 +1,217 @@
+/**
+ * Docker support for noctrace.
+ *
+ * Orchestrates container inspection, HTTP-tool detection, host URL resolution,
+ * watcher injection, and cleanup.  All Docker commands go through the
+ * DockerRunner interface so callers (and tests) can swap in a stub.
+ */
+import path from 'node:path';
+import os from 'node:os';
+// ---------------------------------------------------------------------------
+// Default runner (real child_process)
+// ---------------------------------------------------------------------------
+import { execFileSync, spawn as nodeSpawn } from 'node:child_process';
+export const defaultDockerRunner = {
+    execSync(cmd, args, opts = {}) {
+        return execFileSync(cmd, args, { stdio: opts.stdio ?? 'pipe', timeout: opts.timeout })
+            .toString();
+    },
+    spawn(cmd, args, opts = {}) {
+        return nodeSpawn(cmd, args, opts);
+    },
+};
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+const CONTAINER_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+/**
+ * Returns true when the container name is syntactically safe to pass as an
+ * argv element.  Rejects names that could be used for command injection or
+ * path traversal.
+ */
+export function isValidContainerName(name) {
+    return CONTAINER_NAME_RE.test(name);
+}
+/**
+ * Returns true when a path is free of directory-traversal sequences.
+ * Any segment equal to `..` is rejected regardless of surrounding context.
+ */
+export function isValidContainerPath(p) {
+    return !p.split('/').includes('..');
+}
+// ---------------------------------------------------------------------------
+// Container state
+// ---------------------------------------------------------------------------
+/**
+ * Verify the container is running.  Throws with a user-friendly message when
+ * the container is not found or not running.
+ */
+export function assertContainerRunning(containerArg, runner) {
+    try {
+        runner.execSync('docker', ['inspect', '--format', '{{.State.Running}}', containerArg], { stdio: 'pipe' });
+    }
+    catch {
+        throw new Error(`Container "${containerArg}" not found or not running.\nCheck: docker ps`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Claude config dir inside container
+// ---------------------------------------------------------------------------
+/**
+ * Ask the container for the Claude config directory (respects CLAUDE_CONFIG_DIR).
+ */
+export function resolveClaudeDir(containerArg, runner) {
+    return runner
+        .execSync('docker', ['exec', containerArg, 'sh', '-c', 'echo ${CLAUDE_CONFIG_DIR:-$HOME/.claude}'], { stdio: 'pipe' })
+        .trim();
+}
+/**
+ * Determine which HTTP client is available inside the container.
+ * Tries curl first, falls back to wget, returns 'none' if neither is present.
+ */
+export function detectHttpTool(containerArg, runner) {
+    try {
+        runner.execSync('docker', ['exec', containerArg, 'which', 'curl'], { stdio: 'pipe' });
+        return 'curl';
+    }
+    catch { /* curl not found */ }
+    try {
+        runner.execSync('docker', ['exec', containerArg, 'which', 'wget'], { stdio: 'pipe' });
+        return 'wget';
+    }
+    catch { /* wget not found */ }
+    return 'none';
+}
+// ---------------------------------------------------------------------------
+// Host URL resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the URL the container can use to reach the host.
+ *
+ * Priority:
+ * 1. `host.docker.internal` (works on macOS/Windows Docker Desktop)
+ * 2. Gateway IP from `docker inspect` (Linux Docker)
+ * 3. Fallback to `host.docker.internal` (best-effort)
+ */
+export function resolveHostUrl(containerArg, runner) {
+    try {
+        runner.execSync('docker', ['exec', containerArg, 'getent', 'hosts', 'host.docker.internal'], { stdio: 'pipe' });
+        return 'http://host.docker.internal';
+    }
+    catch { /* not available — try gateway IP */ }
+    try {
+        const gatewayIp = runner
+            .execSync('docker', [
+            'inspect',
+            '--format',
+            '{{range .NetworkSettings.Networks}}{{.Gateway}}{{end}}',
+            containerArg,
+        ], { stdio: 'pipe' })
+            .trim();
+        if (gatewayIp) {
+            return `http://${gatewayIp}`;
+        }
+    }
+    catch { /* ignore */ }
+    return 'http://host.docker.internal';
+}
+// ---------------------------------------------------------------------------
+// Watcher injection
+// ---------------------------------------------------------------------------
+/**
+ * Copy a local script file into the container at `/tmp/noctrace-watcher.sh`,
+ * mark it executable, and return.  The caller is responsible for running it.
+ */
+export function copyWatcherScript(containerArg, localScriptPath, runner) {
+    runner.execSync('docker', ['cp', localScriptPath, `${containerArg}:/tmp/noctrace-watcher.sh`], { stdio: 'pipe' });
+    runner.execSync('docker', ['exec', containerArg, 'chmod', '+x', '/tmp/noctrace-watcher.sh'], { stdio: 'pipe' });
+}
+/**
+ * Start the injected watcher script inside the container in the background.
+ * Returns the spawned process handle (callers can swallow its errors).
+ */
+export function spawnWatcher(containerArg, claudeDir, containerTargetUrl, runner) {
+    const proc = runner.spawn('docker', [
+        'exec', '-d', containerArg,
+        'sh', '-c', '/tmp/noctrace-watcher.sh "$1" "$2" "$3"', '--',
+        claudeDir, containerTargetUrl, containerArg,
+    ], { stdio: 'ignore' });
+    proc.on('error', () => { });
+    return proc;
+}
+// ---------------------------------------------------------------------------
+// Cleanup
+// ---------------------------------------------------------------------------
+/**
+ * Kill the noctrace-watcher process inside the container.
+ * Safe to call after container exit — errors are swallowed.
+ */
+export function cleanupWatcher(containerArg, runner) {
+    try {
+        runner.execSync('docker', ['exec', containerArg, 'sh', '-c', 'pkill -f noctrace-watcher 2>/dev/null || true'], { stdio: 'pipe', timeout: 3000 });
+    }
+    catch { /* container may be gone */ }
+}
+// ---------------------------------------------------------------------------
+// Devcontainer support
+// ---------------------------------------------------------------------------
+/**
+ * Look up a running container by an exact Docker label match.
+ * Returns the container ID (short form), or null when nothing matches.
+ *
+ * Uses `docker ps --filter "label=<label>=<value>" --format "{{.ID}}"`.
+ * The label and value are passed as a single `label=key=value` filter argument
+ * so no shell interpolation occurs.
+ */
+export function findContainerByLabel(label, value, runner) {
+    let output;
+    try {
+        output = runner.execSync('docker', ['ps', '--filter', `label=${label}=${value}`, '--format', '{{.ID}}'], { stdio: 'pipe' });
+    }
+    catch {
+        return null;
+    }
+    const id = output.trim().split('\n')[0]?.trim() ?? '';
+    return id.length > 0 ? id : null;
+}
+/**
+ * Resolve a devcontainer argument to a concrete container ID.
+ *
+ * If `input` looks like a path (starts with `/`, `.`, `./`, or `~/`) it is
+ * resolved to an absolute path and looked up via the canonical
+ * `devcontainer.local_folder` label, falling back to the older
+ * `vsch.local.folder` label.  When neither label matches an error is thrown
+ * with a clear hint pointing the user at `docker ps --filter "label=devcontainer.*"`.
+ *
+ * If `input` is not a path it is treated as a container name/ID.
+ * `isValidContainerName` is checked and the value is returned directly.
+ *
+ * @param cwd - Working directory used to resolve relative paths. Defaults to `process.cwd()`.
+ */
+export function resolveDevcontainerContainer(input, runner, cwd) {
+    const isPath = input.startsWith('/') || input.startsWith('.') || input.startsWith('~/');
+    if (!isPath) {
+        if (!isValidContainerName(input)) {
+            throw new Error(`Invalid container name: "${input}"`);
+        }
+        return input;
+    }
+    // Resolve to an absolute path — devcontainer labels always store absolute paths.
+    // path.resolve does not expand ~ so handle that explicitly.
+    let absPath;
+    if (input.startsWith('~/')) {
+        absPath = path.join(os.homedir(), input.slice(2));
+    }
+    else {
+        absPath = path.resolve(cwd ?? process.cwd(), input);
+    }
+    // Try canonical label first, then the older VS Code label.
+    const id = findContainerByLabel('devcontainer.local_folder', absPath, runner) ??
+        findContainerByLabel('vsch.local.folder', absPath, runner);
+    if (id === null) {
+        throw new Error(`No devcontainer found for path: ${absPath}\n` +
+            `Hint: make sure the devcontainer is running, then check:\n` +
+            `  docker ps --filter "label=devcontainer.local_folder"`);
+    }
+    return id;
+}

package/dist/server/server/routes/api.js

@@ -2,7 +2,7 @@
  * REST API routes for project and session data.
  * All data is read from JSONL files on disk — no in-memory caching.
  */
-import { Router } from 'express';
+import express, { Router } from 'express';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { WebSocket } from 'ws';
@@ -76,6 +76,8 @@ export function buildApiRouter(claudeHome, wss) {
      * When non-empty the client operates in "MCP mode" and shows only these sessions.
      */
     const registeredSessionPaths = new Set();
+    /** Last heartbeat timestamp from Docker container watchers, keyed by container name. */
+    const dockerHeartbeats = new Map();
     /** Broadcast a message to all connected WebSocket clients. */
     function broadcast(msg) {
         const payload = JSON.stringify(msg);
@@ -543,6 +545,103 @@ export function buildApiRouter(claudeHome, wss) {
         }
     });
     // ---------------------------------------------------------------------------
+    // POST /api/docker/stream
+    // ---------------------------------------------------------------------------
+    /**
+     * Receive streamed JSONL content from a Docker container watcher.
+     * Appends raw text to a local sync file under the projects directory.
+     * Chokidar picks up the file change and handles parsing + WebSocket broadcasting.
+     */
+    router.post('/docker/stream', express.text({ type: 'text/plain', limit: '1mb' }), async (req, res) => {
+        try {
+            const containerName = req.headers['x-container-name'];
+            const containerPath = req.headers['x-container-path'];
+            if (typeof containerName !== 'string' || !containerName) {
+                res.status(400).json({ error: 'X-Container-Name header required' });
+                return;
+            }
+            if (typeof containerPath !== 'string' || !containerPath) {
+                res.status(400).json({ error: 'X-Container-Path header required' });
+                return;
+            }
+            if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(containerName)) {
+                res.status(400).json({ error: 'Invalid container name format' });
+                return;
+            }
+            const body = req.body;
+            if (!body || !body.trim()) {
+                res.status(400).json({ error: 'Empty body' });
+                return;
+            }
+            // Extract relative path after /projects/
+            const projectsIdx = containerPath.indexOf('/projects/');
+            if (projectsIdx === -1) {
+                res.status(400).json({ error: 'Container path must contain /projects/' });
+                return;
+            }
+            const relativePath = containerPath.slice(projectsIdx + '/projects/'.length);
+            // Reject path traversal patterns in the relative path
+            if (relativePath.includes('..')) {
+                res.status(400).json({ error: 'Invalid path' });
+                return;
+            }
+            const slashIdx = relativePath.indexOf('/');
+            if (slashIdx === -1) {
+                res.status(400).json({ error: 'Invalid container path structure' });
+                return;
+            }
+            const containerSlug = relativePath.slice(0, slashIdx);
+            const sessionFile = relativePath.slice(slashIdx + 1);
+            const localSlug = `docker--${containerName}--${containerSlug}`;
+            const localPath = path.join(projectsDir, localSlug, sessionFile);
+            try {
+                assertWithinBase(localPath, projectsDir);
+            }
+            catch {
+                res.status(400).json({ error: 'Invalid path' });
+                return;
+            }
+            await fs.mkdir(path.dirname(localPath), { recursive: true });
+            await fs.appendFile(localPath, body.endsWith('\n') ? body : body + '\n');
+            // Auto-register the session
+            if (localPath.endsWith('.jsonl') && !registeredSessionPaths.has(localPath)) {
+                const resolvedPath = path.resolve(localPath);
+                registeredSessionPaths.add(resolvedPath);
+                broadcast({ type: 'session-registered', sessionPath: resolvedPath });
+            }
+            res.json({ ok: true });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            res.status(500).json({ error: message });
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // POST /api/docker/heartbeat
+    // ---------------------------------------------------------------------------
+    /** Keepalive endpoint for Docker container watchers. */
+    router.post('/docker/heartbeat', (req, res) => {
+        const containerName = req.headers['x-container-name'];
+        if (typeof containerName !== 'string' || !containerName) {
+            res.status(400).json({ error: 'X-Container-Name header required' });
+            return;
+        }
+        dockerHeartbeats.set(containerName, Date.now());
+        res.json({ ok: true });
+    });
+    // ---------------------------------------------------------------------------
+    // GET /api/docker/status
+    // ---------------------------------------------------------------------------
+    /** Returns the status of connected Docker containers. */
+    router.get('/docker/status', (_req, res) => {
+        const containers = [];
+        const now = Date.now();
+        for (const [name, ts] of dockerHeartbeats) {
+            containers.push({ name, lastHeartbeat: ts, stale: now - ts > 30_000 });
+        }
+        res.json({ containers });
+    });
+    // ---------------------------------------------------------------------------
     // POST /api/hooks
     // ---------------------------------------------------------------------------
     /**

package/hooks/hooks.json

@@ -4,7 +4,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "curl -s -X POST http://localhost:4117/api/hooks -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
+          "command": "curl -s -X POST \"${NOCTRACE_URL:-http://localhost:4117}/api/hooks\" -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
           "async": true
         }
       ]
@@ -15,7 +15,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "curl -s -X POST http://localhost:4117/api/hooks -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
+          "command": "curl -s -X POST \"${NOCTRACE_URL:-http://localhost:4117}/api/hooks\" -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
           "async": true
         }
       ]
@@ -26,7 +26,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "curl -s -X POST http://localhost:4117/api/hooks -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
+          "command": "curl -s -X POST \"${NOCTRACE_URL:-http://localhost:4117}/api/hooks\" -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
           "async": true
         }
       ]
@@ -37,7 +37,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "curl -s -X POST http://localhost:4117/api/hooks -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
+          "command": "curl -s -X POST \"${NOCTRACE_URL:-http://localhost:4117}/api/hooks\" -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
           "async": true
         }
       ]
@@ -48,7 +48,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "curl -s -X POST http://localhost:4117/api/hooks -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
+          "command": "curl -s -X POST \"${NOCTRACE_URL:-http://localhost:4117}/api/hooks\" -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
           "async": true
         }
       ]
@@ -59,7 +59,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "curl -s -X POST http://localhost:4117/api/hooks -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
+          "command": "curl -s -X POST \"${NOCTRACE_URL:-http://localhost:4117}/api/hooks\" -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
           "async": true
         }
       ]
@@ -70,7 +70,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "curl -s -X POST http://localhost:4117/api/hooks -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
+          "command": "curl -s -X POST \"${NOCTRACE_URL:-http://localhost:4117}/api/hooks\" -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
           "async": true
         }
       ]
@@ -81,7 +81,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "curl -s -X POST http://localhost:4117/api/hooks -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
+          "command": "curl -s -X POST \"${NOCTRACE_URL:-http://localhost:4117}/api/hooks\" -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
           "async": true
         }
       ]
@@ -92,7 +92,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "curl -s -X POST http://localhost:4117/api/hooks -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
+          "command": "curl -s -X POST \"${NOCTRACE_URL:-http://localhost:4117}/api/hooks\" -H 'Content-Type: application/json' --data-raw \"$(cat)\"",
           "async": true
         }
       ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "noctrace",
-  "version": "0.9.0",
+  "version": "1.1.0",
   "description": "Claude Code observability — DevTools-style waterfall visualizer for AI agent workflows, token tracking, and context health monitoring",
   "type": "module",
   "license": "MIT",