totopo 3.8.1 → 3.9.0

package/README.md

@@ -236,13 +236,23 @@ To clear memory: `npx totopo` → **Manage totopo > Clear agent memory**.
         └── shadows/    # container-local shadow path storage
 ```
 
+## Voice Mode (microphone)
+
+Claude Code's `/voice` records from a mic via SoX, but a container has none (on Docker Desktop the Linux VM has no device passthrough). totopo bridges your host mic in over a local PulseAudio server — **opt-in per workspace** from **Manage Workspace → Voice / audio**.
+
+**macOS (automated):** in that menu, **Enable wiring**, then **Install pulseaudio → Start host server → Test microphone** (approve the mic prompt for your terminal under **System Settings → Privacy & Security → Microphone**). Open a session and run `/voice`. The main menu reminds you while the server runs — stop it there when done.
+
+**Linux / Windows (manual):** automation is macOS-only. **Enable wiring**, then run your own PulseAudio server reachable at TCP `4713` (load `module-native-protocol-tcp`). It must accept totopo's cookie at `~/.totopo/pulse-cookie` (mounted read-only into the container), or load the module with `auth-anonymous=1`. On Windows the source is typically the WSLg PulseAudio server.
+
+> **Security:** while running, the server exposes your mic on a local TCP port, gated by an `auth-ip-acl` (private networks only) and — the real gate — a **dedicated, rotating cookie**: totopo-owned (not your general PulseAudio credential), mounted read-only, regenerated on every server start, so a leaked cookie dies on the next restart. Still, run the server only while you need voice and stop it after. A deliberate widening of totopo's boundary — see [Threat Model](#threat-model).
+
 ## Troubleshooting
 
 **Move or rename the workspace directory** — re-run `npx totopo` in the new location. totopo detects the path mismatch and guides you through realigning the workspace cache.
 
 **Single machine** — `~/.totopo/` is local. Switching machines requires re-running setup in each workspace.
 
-**Audio** — `sox` is included (required by Claude Code for voice mode), but audio passthrough depends on your OS. macOS, Linux, and Windows each require different device configuration.
+**Voice mode / audio** — `/voice` needs a microphone, which a container does not have by default. Enable it under **Manage Workspace → Voice / audio**; see [Voice Mode](#voice-mode-microphone).
 
 **Shift+Enter not working in VS Code terminal** — add this to your VS Code keybindings (`Cmd+Shift+P` → "Open Keyboard Shortcuts (JSON)"):
 
@@ -269,6 +279,8 @@ Totopo makes everyday agent mistakes safer. It is not built to stop a determined
 - Container escapes. Totopo uses a non-root user and `no-new-privileges`, but no capability drops or seccomp profiles. For stronger isolation, use a microVM sandbox.
 - Edits to your working tree. The workspace is bind-mounted, so agent changes land on your real files. Commit often.
 
+**Voice mode widens this boundary** — enabling the mic bridge runs a host PulseAudio server that exposes your microphone over a local TCP port (cookie- and ACL-gated) and that totopo never stops for you. Opt in only while dictating; see [Voice Mode](#voice-mode-microphone).
+
 ## Disclaimer
 
 MIT licensed and fully open source. Issues welcome — no promises on response time. Use at your own risk.

package/bin/totopo.js

@@ -15,6 +15,7 @@ import { run as globalMenu } from "../dist/commands/global.js";
 import { run as menu } from "../dist/commands/menu.js";
 import { run as onboard } from "../dist/commands/onboard.js";
 import { resetImage, stop, run as workspaceMenu } from "../dist/commands/workspace.js";
+import { isAudioServerRunning } from "../dist/lib/audio-host.js";
 import { GITHUB_README_URL, repairTotopoYaml } from "../dist/lib/totopo-yaml.js";
 import { deriveContainerName, findTotopoYamlDir, listWorkspaceIds, resolveWorkspace } from "../dist/lib/workspace-identity.js";
 
@@ -152,7 +153,10 @@ while (showMenu) {
     const activeCount = activeNames.length;
     const workspaceRunning = activeNames.some((n) => n === containerName);
 
-    const action = await menu({ ctx: workspace, activeCount, workspaceRunning, version });
+    // Host audio server is global and totopo never stops it on its own; surface it in the status box while up.
+    const audioServerRunning = isAudioServerRunning();
+
+    const action = await menu({ ctx: workspace, activeCount, workspaceRunning, audioServerRunning, version });
 
     switch (action) {
         case "dev":

package/dist/commands/dev.js

@@ -8,13 +8,14 @@ import { existsSync } from "node:fs";
 import { join, relative } from "node:path";
 import { cancel, confirm, isCancel, log, outro, select } from "@clack/prompts";
 import { buildAgentContextDocs, buildAgentMountArgs, injectAgentContext } from "../lib/agent-context.js";
-import { CONTAINER_STARTUP, CONTAINER_WORKSPACE, GIT_MODE, LABEL_GIT_MODE, LABEL_MANAGED, LABEL_PROFILE, LABEL_RUNTIME_ENV, LABEL_SHADOWS, PROFILE, RUNTIME_ENV, } from "../lib/constants.js";
+import { ensureCookieFile } from "../lib/audio-host.js";
+import { AUDIO_COOKIE_CONTAINER_PATH, AUDIO_PULSE_SERVER, AUDIODRIVER_VALUE, CONTAINER_STARTUP, CONTAINER_WORKSPACE, GIT_MODE, LABEL_AUDIO, LABEL_GIT_MODE, LABEL_MANAGED, LABEL_PROFILE, LABEL_RUNTIME_ENV, LABEL_SHADOWS, PROFILE, RUNTIME_ENV, } from "../lib/constants.js";
 import { buildDockerfile, buildImageWithTempfile, computeBuildHash } from "../lib/dockerfile-builder.js";
 import { isImageStale } from "../lib/migrate-to-latest.js";
 import { buildPnpmStoreMountArgs } from "../lib/pnpm-store.js";
 import { buildShadowMountArgs, ensureShadowsInSync, expandShadowPatterns } from "../lib/shadows.js";
 import { readTotopoYaml } from "../lib/totopo-yaml.js";
-import { readActiveProfile, readGitMode, writeActiveProfile } from "../lib/workspace-identity.js";
+import { readActiveProfile, readAudio, readGitMode, writeActiveProfile } from "../lib/workspace-identity.js";
 // --- Prompt: working directory selection -------------------------------------------------------------------------------------------------
 async function promptWorkdir(workspaceDir, cwd) {
     if (cwd === workspaceDir)
@@ -65,18 +66,19 @@ async function selectProfile(ctx, profiles) {
 }
 // Returns null when the container does not exist (docker inspect exits non-zero).
 function inspectContainer(containerName) {
-    const fmt = `{{.State.Status}}|{{index .Config.Labels "${LABEL_SHADOWS}"}}|{{index .Config.Labels "${LABEL_PROFILE}"}}|{{index .Config.Labels "${LABEL_RUNTIME_ENV}"}}|{{index .Config.Labels "${LABEL_GIT_MODE}"}}`;
+    const fmt = `{{.State.Status}}|{{index .Config.Labels "${LABEL_SHADOWS}"}}|{{index .Config.Labels "${LABEL_PROFILE}"}}|{{index .Config.Labels "${LABEL_RUNTIME_ENV}"}}|{{index .Config.Labels "${LABEL_GIT_MODE}"}}|{{index .Config.Labels "${LABEL_AUDIO}"}}`;
     const result = spawnSync("docker", ["inspect", "--format", fmt, containerName], { encoding: "utf8", stdio: "pipe" });
     if (result.status !== 0)
         return null;
     const clean = (s) => (s === "<no value>" ? "" : s);
-    const [status = "", shadows = "", profile = "", runtimeEnv = "", gitMode = ""] = result.stdout.trim().split("|");
+    const [status = "", shadows = "", profile = "", runtimeEnv = "", gitMode = "", audio = ""] = result.stdout.trim().split("|");
     return {
         status,
         shadowLabel: clean(shadows),
         profileLabel: clean(profile),
         runtimeEnvLabel: clean(runtimeEnv),
         gitModeLabel: clean(gitMode),
+        audioLabel: clean(audio),
     };
 }
 // --- Shadow label ------------------------------------------------------------------------------------------------------------------------
@@ -112,7 +114,7 @@ function runStartup(containerName, quiet) {
     return result.status === 0;
 }
 export function startContainer(opts) {
-    const { containerName, workspaceRoot, cacheDir, templatesDir, activeProfile, profileHook, expandedShadows, envFilePath, hasGit, gitMode, shadowPatterns, workspaceName, noCache, quiet = false, } = opts;
+    const { containerName, workspaceRoot, cacheDir, templatesDir, activeProfile, profileHook, expandedShadows, envFilePath, hasGit, gitMode, audio, audioCookiePath, shadowPatterns, workspaceName, noCache, quiet = false, } = opts;
     const stdio = quiet ? "pipe" : "inherit";
     // --- Sync shadows and build mount args ------------------------------------------------------------------------------------------------
     ensureShadowsInSync(cacheDir, expandedShadows, workspaceRoot);
@@ -141,6 +143,8 @@ export function startContainer(opts) {
         `${LABEL_RUNTIME_ENV}=${runtimeEnvLabel()}`,
         "--label",
         `${LABEL_GIT_MODE}=${gitMode}`,
+        "--label",
+        `${LABEL_AUDIO}=${audio}`,
     ];
     // --- Runtime env vars -----------------------------------------------------------------------------------------------------------------
     const runtimeEnvArgs = [
@@ -150,6 +154,25 @@ export function startContainer(opts) {
         "-e",
         `TOTOPO_GIT_MODE=${gitMode}`,
     ];
+    // --- Audio bridge (Claude Code /voice) ------------------------------------------------------------------------------------------------
+    // When enabled, point SoX 'rec' at the host PulseAudio server. --add-host makes host.docker.internal
+    // resolve on native Linux (it is automatic on Docker Desktop, where the flag is harmless).
+    // When the host cookie exists, mount it read-only and set PULSE_COOKIE so the container can
+    // authenticate; the server requires this shared secret, so only wired containers can connect.
+    const audioCookieArgs = audio && audioCookiePath
+        ? ["-e", `PULSE_COOKIE=${AUDIO_COOKIE_CONTAINER_PATH}`, "-v", `${audioCookiePath}:${AUDIO_COOKIE_CONTAINER_PATH}:ro`]
+        : [];
+    const audioRunArgs = audio
+        ? [
+            "-e",
+            `PULSE_SERVER=${AUDIO_PULSE_SERVER}`,
+            "-e",
+            `AUDIODRIVER=${AUDIODRIVER_VALUE}`,
+            "--add-host",
+            "host.docker.internal:host-gateway",
+            ...audioCookieArgs,
+        ]
+        : [];
     // --- Inspect container state ---------------------------------------------------------------------------------------------------------
     const info = inspectContainer(containerName);
     let containerStatus = info?.status ?? null;
@@ -160,7 +183,8 @@ export function startContainer(opts) {
         const profileChanged = info.profileLabel !== activeProfile;
         const runtimeEnvChanged = info.runtimeEnvLabel !== runtimeEnvLabel();
         const gitModeChanged = info.gitModeLabel !== gitMode;
-        if (shadowChanged || profileChanged || runtimeEnvChanged || gitModeChanged) {
+        const audioChanged = info.audioLabel !== String(audio);
+        if (shadowChanged || profileChanged || runtimeEnvChanged || gitModeChanged || audioChanged) {
             stopAndRemoveContainer(containerName);
             containerStatus = null;
             if (profileChanged) {
@@ -177,6 +201,10 @@ export function startContainer(opts) {
                 if (!quiet)
                     log.info(`Git mode changed (${info.gitModeLabel || "<unset>"} -> ${gitMode}) — recreating container...`);
             }
+            else if (audioChanged) {
+                if (!quiet)
+                    log.info(`Voice/audio ${audio ? "enabled" : "disabled"} — recreating container...`);
+            }
             else {
                 if (!quiet)
                     log.info("Runtime environment updated — recreating container...");
@@ -207,6 +235,7 @@ export function startContainer(opts) {
             ...mountArgs,
             ...envFileArgs,
             ...runtimeEnvArgs,
+            ...audioRunArgs,
             "--security-opt",
             "no-new-privileges:true",
             ...labelArgs,
@@ -287,6 +316,12 @@ export async function run(packageDir, ctx, options) {
     const hasGit = existsSync(join(workspaceDir, ".git"));
     // --- Git mode (per-workspace, host-side .lock) ---------------------------------------------------------------------------------------
     const gitMode = readGitMode(ctx.workspaceId) ?? GIT_MODE.local;
+    // --- Audio bridge opt-in (per-workspace, host-side .lock) ----------------------------------------------------------------------------
+    const audio = readAudio(ctx.workspaceId);
+    // Ensure totopo's dedicated host cookie exists so the read-only mount target is always valid; the
+    // host server rotates it on each cold start. Creating it here (when absent) avoids any need to
+    // recreate the container after the server first starts.
+    const audioCookiePath = audio ? ensureCookieFile() : undefined;
     // --- Start container -----------------------------------------------------------------------------------------------------------------
     const containerOpts = {
         containerName,
@@ -299,6 +334,8 @@ export async function run(packageDir, ctx, options) {
         envFilePath,
         hasGit,
         gitMode,
+        audio,
+        ...(audioCookiePath !== undefined && { audioCookiePath }),
         shadowPatterns,
         workspaceName: ctx.workspaceId,
         ...(options?.noCache !== undefined && { noCache: options.noCache }),

package/dist/commands/menu.js

@@ -9,14 +9,18 @@ import { box, cancel, isCancel, select } from "@clack/prompts";
 import { PROFILE } from "../lib/constants.js";
 import { readActiveProfile } from "../lib/workspace-identity.js";
 export async function run(args) {
-    const { ctx, workspaceRunning, version } = args;
+    const { ctx, workspaceRunning, audioServerRunning, version } = args;
     // --- Read workspace config -----------------------------------------------------------------------------------------------------------
     const activeProfile = readActiveProfile(ctx.workspaceId) ?? PROFILE.default;
     const hasGit = existsSync(join(ctx.workspaceRoot, ".git"));
     // --- Status box ----------------------------------------------------------------------------------------------------------------------
     const containerStatus = workspaceRunning ? "running" : "stopped";
     const gitNotice = hasGit ? "" : `\n${styleText("yellow", "●")} no git — agent changes are not tracked`;
-    box(`workspace:   ${ctx.workspaceId}\nprofile:     ${activeProfile}\ncontainer:   ${containerStatus}${gitNotice}`, ` totopo v${version} `, {
+    // totopo never stops the host audio server itself, so remind the user while it is up.
+    const audioNotice = audioServerRunning
+        ? `\n${styleText("yellow", "●")} audio mic server running (Manage Workspace › Voice / audio)`
+        : "";
+    box(`workspace:   ${ctx.workspaceId}\nprofile:     ${activeProfile}\ncontainer:   ${containerStatus}${gitNotice}${audioNotice}`, ` totopo v${version} `, {
         contentAlign: "left",
         titleAlign: "center",
         width: "auto",

package/dist/commands/workspace.js

@@ -4,10 +4,11 @@
 import { spawnSync } from "node:child_process";
 import { relative } from "node:path";
 import { cancel, confirm, isCancel, log, multiselect, note, outro, path, select, text } from "@clack/prompts";
-import { GIT_MODE } from "../lib/constants.js";
+import { getStatus, IS_MACOS, installPulse, startServer, stopServer, testMic } from "../lib/audio-host.js";
+import { AUDIO_TCP_PORT, GIT_MODE } from "../lib/constants.js";
 import { countPatternHits } from "../lib/shadows.js";
 import { buildDefaultTotopoYaml, readTotopoYaml, writeTotopoYaml } from "../lib/totopo-yaml.js";
-import { readGitMode, writeGitMode } from "../lib/workspace-identity.js";
+import { readAudio, readGitMode, writeAudio, writeGitMode } from "../lib/workspace-identity.js";
 // --- Shadow paths menu -------------------------------------------------------------------------------------------------------------------
 async function shadowPathsMenu(ctx) {
     const yaml = readTotopoYaml(ctx.workspaceRoot);
@@ -161,6 +162,68 @@ async function gitModeMenu(ctx) {
     log.success(`Git mode set to ${choice}.`);
     await promptStopContainer(ctx);
 }
+// --- Voice / audio menu ------------------------------------------------------------------------------------------------------------------
+async function audioMenu(ctx) {
+    while (true) {
+        const wiring = readAudio(ctx.workspaceId);
+        const status = getStatus();
+        const serverLine = !status.installed ? "not installed" : status.running ? `running on TCP ${AUDIO_TCP_PORT}` : "installed, stopped";
+        note(`wiring:       ${wiring ? "enabled" : "disabled"}  (this workspace)\n` +
+            `host server:  ${serverLine}` +
+            (status.version ? `\nversion:      ${status.version}` : ""), "Voice / audio");
+        log.message("Claude Code /voice needs a microphone, which the container does not have.\n" +
+            "Enable wiring (per-workspace) and run a host PulseAudio server that streams your mic in.\n" +
+            "Access needs a dedicated, rotating cookie (and is limited to private networks), but the server\n" +
+            "still exposes your mic over a local TCP port — totopo never stops it for you, so stop it here when done.");
+        if (!IS_MACOS) {
+            log.info("Host server control is automated on macOS only. On Linux/Windows, start a PulseAudio server on the host manually — see the README.");
+        }
+        const options = [
+            { value: "toggle", label: wiring ? "Disable wiring" : "Enable wiring", hint: "PulseAudio env for this workspace's container" },
+        ];
+        if (IS_MACOS) {
+            if (!status.installed)
+                options.push({ value: "install", label: "Install pulseaudio", hint: "via Homebrew" });
+            if (status.installed && !status.running)
+                options.push({ value: "start", label: "Start host server", hint: `TCP ${AUDIO_TCP_PORT}` });
+            if (status.running) {
+                options.push({ value: "test", label: "Test microphone", hint: "record 3s and check capture" });
+                options.push({ value: "stop", label: "Stop host server" });
+            }
+        }
+        options.push({ value: "back", label: "← Back" });
+        const action = await select({ message: "Voice / audio:", options });
+        if (isCancel(action) || action === "back")
+            return;
+        if (action === "toggle") {
+            const next = !wiring;
+            writeAudio(ctx.workspaceId, next);
+            log.success(`Voice/audio wiring ${next ? "enabled" : "disabled"} for this workspace.`);
+            await promptStopContainer(ctx);
+            continue;
+        }
+        let result;
+        if (action === "install") {
+            result = installPulse();
+        }
+        else if (action === "start") {
+            result = startServer();
+        }
+        else if (action === "stop") {
+            result = stopServer();
+        }
+        else {
+            log.step("Recording 3 seconds — speak now...");
+            result = testMic();
+        }
+        if (result.ok) {
+            log.success(result.message);
+        }
+        else {
+            log.warn(result.message);
+        }
+    }
+}
 // --- Prompt to stop container ------------------------------------------------------------------------------------------------------------
 async function promptStopContainer(ctx) {
     const containerName = ctx.containerName;
@@ -208,6 +271,7 @@ export async function run(ctx) {
         const options = [
             { value: "git-mode", label: "Git mode", hint: `current: ${currentGitMode}` },
             { value: "shadow-paths", label: "Shadow paths", hint: "manage shadow patterns" },
+            { value: "audio", label: "Voice / audio", hint: "Claude Code /voice mic setup" },
             { value: "rebuild", label: "Rebuild container", hint: "force a fresh image build" },
             { value: "clean-rebuild", label: "Clean rebuild", hint: "fresh build, no cache" },
             { value: "reset", label: "Reset config", hint: "restore totopo.yaml to defaults" },
@@ -224,6 +288,9 @@ export async function run(ctx) {
             case "shadow-paths":
                 await shadowPathsMenu(ctx);
                 break;
+            case "audio":
+                await audioMenu(ctx);
+                break;
             case "rebuild":
                 return "rebuild";
             case "clean-rebuild":

package/dist/lib/audio-host.js

@@ -0,0 +1,158 @@
+// =========================================================================================================================================
+// src/lib/audio-host.ts - Host-side PulseAudio control for Claude Code /voice (macOS-first).
+// Bridges the host microphone into the container over TCP so SoX 'rec' inside the container can capture audio.
+// All actions run on the host; the per-workspace wiring is the .lock audio flag (see dev.ts).
+// =========================================================================================================================================
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { AUDIO_TCP_PORT, TOTOPO_DIR } from "./constants.js";
+// Coarse network filter: loopback plus the private (RFC1918) ranges Docker may present container
+// traffic from. This keeps the server off the public internet without guessing the exact source IP
+// a given Docker setup uses (which varies), so /voice connects reliably. Actual access control is the
+// shared cookie (see hostCookiePath): a client on these networks still cannot connect without it.
+const ACL = "127.0.0.1;10.0.0.0/8;172.16.0.0/12;192.168.0.0/16";
+// Host-side daemon control (install/start/stop/test) is automated on macOS only.
+// Other platforms still get accurate running/installed status; setup is documented in the README.
+export const IS_MACOS = process.platform === "darwin";
+// --- Probes ------------------------------------------------------------------------------------------------------------------------------
+// True if a command exists on PATH.
+function have(cmd) {
+    return spawnSync("which", [cmd], { stdio: "pipe" }).status === 0;
+}
+// True if pulseaudio is installed on the host.
+function isPulseInstalled() {
+    return have("pulseaudio");
+}
+// First line of `pulseaudio --version`, or null when unavailable.
+function pulseVersion() {
+    const r = spawnSync("pulseaudio", ["--version"], { encoding: "utf8", stdio: "pipe" });
+    if (r.status !== 0 || !r.stdout)
+        return null;
+    return r.stdout.trim().split("\n")[0] ?? null;
+}
+// True when a PulseAudio daemon is currently running on the host. Safe on any platform.
+export function isAudioServerRunning() {
+    return spawnSync("pulseaudio", ["--check"], { stdio: "pipe" }).status === 0;
+}
+// --- Status ------------------------------------------------------------------------------------------------------------------------------
+// Snapshot of the host audio server for the Voice menu.
+export function getStatus() {
+    const installed = isPulseInstalled();
+    return {
+        installed,
+        running: isAudioServerRunning(),
+        version: installed ? pulseVersion() : null,
+    };
+}
+// --- Actions -----------------------------------------------------------------------------------------------------------------------------
+// Install pulseaudio via Homebrew (macOS). Inherits stdio so brew progress is visible.
+export function installPulse() {
+    if (isPulseInstalled())
+        return { ok: true, message: "pulseaudio is already installed." };
+    if (!have("brew"))
+        return { ok: false, message: "Homebrew not found. Install it from https://brew.sh then retry." };
+    const r = spawnSync("brew", ["install", "pulseaudio"], { stdio: "inherit" });
+    if (r.status === 0)
+        return { ok: true, message: "pulseaudio installed." };
+    return { ok: false, message: "brew install pulseaudio failed." };
+}
+// PulseAudio authenticates native-protocol clients with a 256-byte shared-secret cookie.
+const COOKIE_BYTES = 256;
+// totopo uses its OWN cookie for the container (TCP) path, kept separate from the user's general
+// PulseAudio cookie and never mounting that general credential into the container. It lives at a
+// stable path that survives reboots, so a running container keeps working without a rebuild.
+export function hostCookiePath() {
+    return join(homedir(), TOTOPO_DIR, "pulse-cookie");
+}
+// Write a fresh random cookie to `path`, in place (truncating the same file) so a container's
+// read-only bind mount sees the new bytes live - no rebuild needed. 0600: only the host user reads it.
+function writeFreshCookie(path) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, randomBytes(COOKIE_BYTES), { mode: 0o600 });
+}
+// Ensure the cookie file exists WITHOUT rotating it (create-if-missing). Used at container-create time
+// so the mount target is always valid; never clobbers a cookie a running server is already using.
+export function ensureCookieFile() {
+    const path = hostCookiePath();
+    if (!existsSync(path))
+        writeFreshCookie(path);
+    return path;
+}
+// Start the host daemon: capture the Mac mic (coreaudio) and expose it to the container over TCP.
+// module-coreaudio-detect      : auto-create sources/sinks for CoreAudio devices (the mic).
+// module-always-sink           : guarantee a sink exists (avoids warnings).
+// module-native-protocol-unix  : let host-side pactl/parec connect over the local socket (uses the
+//                                daemon's own default cookie, so testMic is unaffected by our cookie).
+// module-native-protocol-tcp   : expose the server to the container over TCP. No auth-anonymous, so
+//                                clients must present totopo's dedicated cookie (auth-cookie); the IP
+//                                ACL is defense-in-depth, restricting which hosts may even connect.
+export function startServer() {
+    if (!isPulseInstalled())
+        return { ok: false, message: "pulseaudio is not installed. Install it first." };
+    if (isAudioServerRunning())
+        return { ok: true, message: "pulseaudio is already running." };
+    // Rotate the dedicated TCP cookie on each cold start: a cookie leaked from a previous session is
+    // invalidated here. Written in place so a running container picks it up without a rebuild.
+    const cookie = hostCookiePath();
+    writeFreshCookie(cookie);
+    const modules = [
+        "--load=module-coreaudio-detect",
+        "--load=module-always-sink",
+        "--load=module-native-protocol-unix",
+        `--load=module-native-protocol-tcp auth-ip-acl=${ACL} auth-cookie=${cookie} port=${AUDIO_TCP_PORT}`,
+    ];
+    const r = spawnSync("pulseaudio", ["--daemonize=yes", "-n", "--exit-idle-time=-1", ...modules], { stdio: "pipe" });
+    if (r.status !== 0)
+        return { ok: false, message: "pulseaudio failed to start. Approve any macOS firewall prompt, then retry." };
+    if (isAudioServerRunning())
+        return { ok: true, message: `pulseaudio started on TCP ${AUDIO_TCP_PORT}.` };
+    return { ok: false, message: "pulseaudio did not come up. Check Console.app logs and retry." };
+}
+// Stop the host daemon. Safe to call when nothing is running.
+export function stopServer() {
+    if (!isPulseInstalled())
+        return { ok: true, message: "pulseaudio is not installed; nothing to stop." };
+    if (!isAudioServerRunning())
+        return { ok: true, message: "pulseaudio is not running." };
+    spawnSync("pulseaudio", ["--kill"], { stdio: "pipe" });
+    if (!isAudioServerRunning())
+        return { ok: true, message: "pulseaudio stopped." };
+    return { ok: false, message: "Could not stop pulseaudio." };
+}
+// Record ~3s from the default source and inspect it. All-zero capture almost always means the
+// macOS microphone permission was denied. Returns the captured byte count for the menu to report.
+export function testMic() {
+    if (!isAudioServerRunning())
+        return { ok: false, message: "pulseaudio is not running. Start it first.", bytes: 0 };
+    if (!have("parec"))
+        return { ok: false, message: "parec not found - reinstall pulseaudio (it ships parec/pactl).", bytes: 0 };
+    const r = spawnSync("parec", ["--channels=1", "--rate=16000", "--format=s16le"], {
+        timeout: 3000,
+        maxBuffer: 16000 * 2 * 5, // ~5s of 16kHz mono s16 headroom
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    const buf = r.stdout ?? Buffer.alloc(0);
+    const bytes = buf.length;
+    if (bytes < 1000) {
+        return { ok: false, message: `Captured only ${bytes} bytes - the host could not read the microphone source.`, bytes };
+    }
+    let nonZero = false;
+    for (const b of buf) {
+        if (b !== 0) {
+            nonZero = true;
+            break;
+        }
+    }
+    if (!nonZero) {
+        return {
+            ok: false,
+            message: "Captured audio but it was pure silence - the macOS microphone permission is almost certainly denied. " +
+                "Approve your terminal under System Settings > Privacy & Security > Microphone, then retry.",
+            bytes,
+        };
+    }
+    return { ok: true, message: `Captured ${bytes} bytes of real audio - mic capture works.`, bytes };
+}

package/dist/lib/constants.js

@@ -39,6 +39,7 @@ export const LABEL_PROFILE = "totopo.profile";
 export const LABEL_RUNTIME_ENV = "totopo.runtime-env";
 export const LABEL_GIT_MODE = "totopo.git-mode";
 export const LABEL_BUILD_HASH = "totopo.build-hash";
+export const LABEL_AUDIO = "totopo.audio";
 // Built-in profile names (must match keys in buildDefaultTotopoYaml in totopo-yaml.ts)
 export const PROFILE = {
     default: "default",
@@ -62,3 +63,13 @@ export const RUNTIME_ENV = {
     DISABLE_TELEMETRY: "1", // Container sessions should not phone home
     DISABLE_UPGRADE_COMMAND: "1", // /upgrade is wrong path inside container; totopo manages CLI version
 };
+// Audio bridge for Claude Code /voice (opt-in, per-workspace via the .lock audio flag).
+// When enabled, dev.ts injects PULSE_SERVER + AUDIODRIVER and an --add-host so SoX 'rec'
+// inside the container reaches a PulseAudio server running on the host.
+// The host must be host.docker.internal, never 127.0.0.1 (which is the container itself).
+export const AUDIO_TCP_PORT = 4713;
+export const AUDIO_PULSE_SERVER = `tcp:host.docker.internal:${AUDIO_TCP_PORT}`;
+export const AUDIODRIVER_VALUE = "pulseaudio";
+// Where the host PulseAudio cookie is bind-mounted inside the container. PULSE_COOKIE points here so
+// libpulse presents the shared secret; only containers totopo hands the cookie to can authenticate.
+export const AUDIO_COOKIE_CONTAINER_PATH = `${CONTAINER_HOME}/.config/pulse/cookie`;

package/dist/lib/migrate-to-latest.js

@@ -421,6 +421,38 @@ export function migrateAddGitMode() {
     }
     return migrated;
 }
+/**
+ * Pre-v3.9.0: Add the audio=false field to .lock files. False is the default, so this is a
+ * cosmetic write that makes the field visible on disk; runtime behavior is unchanged for
+ * existing workspaces (microphone bridging stays off until explicitly enabled). Idempotent -
+ * skips files that already have the field. Prints a one-time clack note() when any workspace
+ * was newly migrated so users discover the new feature. Returns the count for testing purposes;
+ * the registered Migration entry ignores it.
+ */
+export function migrateAddAudio() {
+    const baseDir = getWorkspacesBaseDir();
+    if (!existsSync(baseDir))
+        return 0;
+    let migrated = 0;
+    for (const entry of readdirSync(baseDir)) {
+        const lockPath = join(baseDir, entry, LOCK_FILE);
+        try {
+            const content = readFileSync(lockPath, "utf8");
+            if (content.includes(`${LOCK_KEYS.audio}=`))
+                continue;
+            const trimmed = content.endsWith("\n") ? content : `${content}\n`;
+            writeFileSync(lockPath, `${trimmed}${LOCK_KEYS.audio}=false\n`);
+            migrated++;
+        }
+        catch {
+            // unreadable -- skip, will surface as a broken workspace elsewhere
+        }
+    }
+    if (migrated > 0) {
+        note(`totopo v3.9.0 adds opt-in microphone support for Claude Code's /voice.\nEnable it per workspace via the totopo menu > Manage Workspace > Voice / audio.\nOn macOS totopo can install and run the host audio bridge for you; on Linux/Windows you point it at your own PulseAudio server.`, "Voice / audio");
+    }
+    return migrated;
+}
 /**
  * v3.2.1 and earlier: Remove deprecated fields from totopo.yaml.
  * - schema_version: redundant, totopo validates with the bundled JSON schema at runtime
@@ -493,6 +525,7 @@ function buildMigrations(cwd, skipAnyConfirmations) {
             run: () => migrateRemoveDeprecatedYamlFields(cwd),
         },
         { from: "v3.4.0", description: "Add git_mode=local to .lock files (preserves pre-v3.4.0 behavior)", run: migrateAddGitMode },
+        { from: "v3.9.0", description: "Add audio=false to .lock files (preserves pre-v3.9.0 behavior)", run: migrateAddAudio },
     ];
 }
 /** Run all migrations in order. Called early in bin/totopo.js startup. */

package/dist/lib/workspace-identity.js

@@ -12,6 +12,7 @@ export const LOCK_KEYS = {
     workspaceRoot: "root",
     activeProfile: "profile",
     gitMode: "git_mode",
+    audio: "audio",
 };
 /** Reverse lookup: file key → LockFile field name, used during parsing. */
 const FILE_KEY_TO_FIELD = Object.fromEntries(Object.entries(LOCK_KEYS).map(([field, key]) => [key, field]));
@@ -55,6 +56,7 @@ function parseLockFile(workspaceId) {
             workspaceRoot: partial.workspaceRoot,
             activeProfile: partial.activeProfile ?? PROFILE.default,
             gitMode: partial.gitMode ?? GIT_MODE.local,
+            audio: partial.audio ?? "false",
         };
     }
     catch {
@@ -79,6 +81,7 @@ export function writeLockFile(workspaceId, workspaceRoot) {
         workspaceRoot,
         activeProfile: existing?.activeProfile ?? PROFILE.default,
         gitMode: existing?.gitMode ?? GIT_MODE.local,
+        audio: existing?.audio ?? "false",
     });
 }
 /** Read the active profile name. Returns null if lock file is missing. */
@@ -107,13 +110,24 @@ export function writeGitMode(workspaceId, gitMode) {
         return;
     writeLockFileInternal(workspaceId, { ...existing, gitMode });
 }
+/** Read the audio (Claude Code /voice) opt-in flag. Defaults to false when unset or lock file is missing. */
+export function readAudio(workspaceId) {
+    return parseLockFile(workspaceId)?.audio === "true";
+}
+/** Write the audio opt-in flag. No-op if the lock file is missing. Preserves all other fields. */
+export function writeAudio(workspaceId, audio) {
+    const existing = parseLockFile(workspaceId);
+    if (!existing)
+        return;
+    writeLockFileInternal(workspaceId, { ...existing, audio: String(audio) });
+}
 // --- Workspace directory initialization --------------------------------------------------------------------------------------------------
 /** Initialize ~/.totopo/workspaces/<workspace_id>/ with lock file and subdirs. */
-export function initWorkspaceDir(workspaceId, workspaceRoot, activeProfile = PROFILE.default, gitMode = GIT_MODE.local) {
+export function initWorkspaceDir(workspaceId, workspaceRoot, activeProfile = PROFILE.default, gitMode = GIT_MODE.local, audio = false) {
     const dir = getWorkspaceDir(workspaceId);
     mkdirSync(join(dir, AGENTS_DIR), { recursive: true });
     mkdirSync(join(dir, SHADOWS_DIR), { recursive: true });
-    writeLockFileInternal(workspaceId, { workspaceRoot, activeProfile, gitMode });
+    writeLockFileInternal(workspaceId, { workspaceRoot, activeProfile, gitMode, audio: String(audio) });
 }
 // --- Listing -----------------------------------------------------------------------------------------------------------------------------
 /** List all registered workspace IDs (directories with a .lock file) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totopo",
-  "version": "3.8.1",
+  "version": "3.9.0",
   "description": "Run AI coding agents safely in your local codebase",
   "type": "module",
   "bin": {

package/templates/Dockerfile

@@ -31,8 +31,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     git curl wget bash zsh make \
     # Build essentials
     build-essential pkg-config libssl-dev \
-    # Utilities
-    jq unzip zip tree htop procps lsb-release gnupg ca-certificates sox file bubblewrap \
+    # Utilities (libsox-fmt-pulse + pulseaudio-utils let SoX 'rec' reach a host PulseAudio server for Claude Code /voice; dormant unless wired at runtime)
+    jq unzip zip tree htop procps lsb-release gnupg ca-certificates sox libsox-fmt-pulse pulseaudio-utils file bubblewrap \
     # Modern search/navigation tools (fd-find installs the binary as 'fdfind'; symlinked to 'fd' below)
     ripgrep fzf fd-find \
     # Database clients

package/templates/context/responsibilities.md

@@ -2,3 +2,4 @@
 
 At the start of every session:
 - Briefly tell the user they are in a totopo sandbox and mention key limitations (totopo git mode, no host filesystem access outside the workspace).
+- Add a short note that if they want to use or troubleshoot microphone input (Claude Code `/voice`), it is set up from the totopo menu under **Manage Workspace -> Voice / audio** — not from inside the container.