totopo 3.9.0 → 3.10.0-rc-1

package/README.md

@@ -81,8 +81,8 @@ On every run, totopo shows the workspace menu:
 
 - **Open session** — start or resume the dev container and connect
 - **Stop container** — stop the running container
-- **Manage Workspace** — git mode, shadow paths, rebuild, reset config
-- **Manage totopo** — multi-workspace management (stop containers, clear memory, uninstall)
+- **Settings** — git mode, shadow paths, voice, rebuild, reset config
+- **Advanced** — multi-workspace management (stop containers, clear memory, uninstall)
 
 ### Working directory
 
@@ -106,7 +106,7 @@ Every session runs inside a Docker container. Your code is bind-mounted from the
 
 ### Git Modes
 
-Each workspace has a git mode (set via **Manage Workspace > Git mode**) that controls what git operations are permitted inside the container:
+Each workspace has a git mode (set via **Settings > Git mode**) that controls what git operations are permitted inside the container:
 
 | Mode | Local mutations | Remote (push/pull/fetch/clone) |
 |---|---|---|
@@ -148,7 +148,7 @@ profiles:
 
 New workspaces ship with the `default` profile active and an `extended` profile (Go, Java, Rust, Bun) included as a commented-out template — uncomment to enable. When multiple profiles are defined, totopo prompts you to pick one at session start (the choice is remembered). A profile change triggers a container rebuild on the next session.
 
-The base image is defined in [`templates/Dockerfile`](templates/Dockerfile) — inspect it to see what's already included before adding your own layers. To force a fully fresh build (no Docker layer cache), use **Manage Workspace > Clean rebuild**.
+The base image is defined in [`templates/Dockerfile`](templates/Dockerfile) — inspect it to see what's already included before adding your own layers. To force a fully fresh build (no Docker layer cache), use **Settings > Clean rebuild**.
 
 ### Shadow Paths
 
@@ -161,7 +161,7 @@ shadow_paths:
   - .env*           # hides .env, .env.local, etc. from agents
 ```
 
-Patterns follow gitignore syntax — patterns without a `/` match at any depth. Manage via **Manage Workspace > Shadow paths** or edit `totopo.yaml` directly. Changes take effect on the next session.
+Patterns follow gitignore syntax — patterns without a `/` match at any depth. Manage via **Settings > Shadow paths** or edit `totopo.yaml` directly. Changes take effect on the next session.
 
 Git-tracked paths are skipped to avoid worktree diversions. Shadowing them has no privacy benefit anyway since agents can `git show` tracked content. To hide a file, untrack it and add it to `.gitignore` first.
 
@@ -218,7 +218,7 @@ Agent session data (conversation history, settings) is stored per workspace and
 └── codex/              # mounted as ~/.codex/ inside the container
 ```
 
-To clear memory: `npx totopo` → **Manage totopo > Clear agent memory**.
+To clear memory: `npx totopo` → **Advanced > Clear agent memory**.
 
 ## What Gets Installed
 
@@ -238,11 +238,11 @@ To clear memory: `npx totopo` → **Manage totopo > Clear agent memory**.
 
 ## 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**.
+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 **Settings → 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.
+**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. For hands-off control, turn **Auto start/stop** on in the same menu: totopo then starts the server when a voice-enabled session opens and stops it once your last session exits, so you never start or stop it by hand.
 
-**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.
+**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/global/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).
 
@@ -252,7 +252,7 @@ Claude Code's `/voice` records from a mic via SoX, but a container has none (on
 
 **Single machine** — `~/.totopo/` is local. Switching machines requires re-running setup in each workspace.
 
-**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).
+**Voice mode / audio** — `/voice` needs a microphone, which a container does not have by default. Enable it under **Settings → 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)"):
 

package/bin/totopo.js

@@ -9,12 +9,12 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { cancel, confirm, isCancel, log, select } from "@clack/prompts";
+import { run as advancedMenu } from "../dist/commands/advanced.js";
 import { run as dev } from "../dist/commands/dev.js";
 import { run as doctor } from "../dist/commands/doctor.js";
-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 { resetImage, run as settingsMenu, stop } from "../dist/commands/settings.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";
@@ -113,15 +113,15 @@ if (!workspace) {
             message: "What would you like to do?",
             options: [
                 { value: "setup", label: "Set up totopo for this directory" },
-                { value: "manage", label: "Manage totopo →" },
+                { value: "advanced", label: "Advanced" },
             ],
         });
         if (isCancel(choice)) {
             cancel();
             process.exit(0);
         }
-        if (choice === "manage") {
-            await globalMenu();
+        if (choice === "advanced") {
+            await advancedMenu();
             process.exit(0);
         }
     }
@@ -132,7 +132,7 @@ if (!workspace) {
 }
 
 // --- Doctor (silent pre-check) -----------------------------------------------------------------------------------------------------------
-const doctorResult = await doctor(null, false);
+const doctorResult = await doctor(false);
 if (!doctorResult.ok) {
     console.error("  Fix the issues above and re-run totopo.");
     console.error("");
@@ -166,7 +166,7 @@ while (showMenu) {
             await stop(workspace.containerName);
             break;
         case "settings": {
-            const settingsResult = await workspaceMenu(workspace);
+            const settingsResult = await settingsMenu(workspace);
             if (settingsResult === "rebuild") {
                 await resetImage(workspace.containerName);
                 await dev(packageDir, workspace);
@@ -178,8 +178,8 @@ while (showMenu) {
             }
             break;
         }
-        case "manage-totopo": {
-            const result = await globalMenu(workspace.workspaceId);
+        case "advanced": {
+            const result = await advancedMenu(workspace.workspaceId);
             if (result === "back") showMenu = true;
             break;
         }

package/dist/commands/{global.js → advanced.js}

@@ -1,5 +1,5 @@
 // =========================================================================================================================================
-// src/commands/global.ts - Manage totopo menu (global, all workspaces)
+// src/commands/advanced.ts - Advanced menu: less-common operations (stop containers, clear agent memory, remove images, uninstall)
 // =========================================================================================================================================
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
@@ -239,11 +239,11 @@ async function uninstallTotopo() {
     }
     outro("totopo uninstalled. Re-run npx totopo to set up again.");
 }
-// --- Manage totopo menu ------------------------------------------------------------------------------------------------------------------
+// --- Advanced menu -----------------------------------------------------------------------------------------------------------------------
 export async function run(currentWorkspaceId) {
     while (true) {
         const action = await select({
-            message: "Manage totopo:",
+            message: "Advanced:",
             options: [
                 { value: "stop-containers", label: "Stop containers", hint: "pick running containers" },
                 { value: "clear-memory", label: "Clear agent memory", hint: "pick workspaces to clear" },

package/dist/commands/dev.js

@@ -8,9 +8,10 @@ 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 { 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 { connectedSessionCount, containerSessionCount, ensureCookieFile, IS_MACOS, isAudioServerRunning, startServer, stopServer, } from "../lib/audio-host.js";
+import { AUDIO_COOKIE_CONTAINER_PATH, AUDIO_MODE, 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 { readAudioMode } from "../lib/global-config.js";
 import { isImageStale } from "../lib/migrate-to-latest.js";
 import { buildPnpmStoreMountArgs } from "../lib/pnpm-store.js";
 import { buildShadowMountArgs, ensureShadowsInSync, expandShadowPatterns } from "../lib/shadows.js";
@@ -34,6 +35,15 @@ async function promptWorkdir(workspaceDir, cwd) {
     }
     return choice === "here" ? `${CONTAINER_WORKSPACE}/${relPath}` : CONTAINER_WORKSPACE;
 }
+// --- Countdown helper --------------------------------------------------------------------------------------------------------------------
+// Print a message, then tick down one line per second. Used so a transient warning (e.g. the host audio
+// server failed to auto-start) stays on screen long enough to read before the session connects anyway.
+async function countdown(seconds, message) {
+    for (let remaining = seconds; remaining > 0; remaining--) {
+        log.info(`${message} in ${remaining}...`);
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+}
 // --- Profile selection -------------------------------------------------------------------------------------------------------------------
 async function selectProfile(ctx, profiles) {
     const profileNames = Object.keys(profiles);
@@ -318,6 +328,20 @@ export async function run(packageDir, ctx, options) {
     const gitMode = readGitMode(ctx.workspaceId) ?? GIT_MODE.local;
     // --- Audio bridge opt-in (per-workspace, host-side .lock) ----------------------------------------------------------------------------
     const audio = readAudio(ctx.workspaceId);
+    // --- Auto-start host audio server (automatic mode, macOS) ----------------------------------------------------------------------------
+    // When wiring is on and the workspace is in automatic mode, bring the host server up before the
+    // container starts so the cookie it rotates is already in place for the read-only mount below
+    // (ensureCookieFile then no-ops). A failure never blocks the session - warn and count down so the
+    // message is readable, then connect anyway.
+    if (IS_MACOS && audio && readAudioMode() === AUDIO_MODE.automatic && !isAudioServerRunning()) {
+        const res = startServer();
+        if (res.ok)
+            log.info("Host audio server started (voice input ready).");
+        else {
+            log.warn(res.message);
+            await countdown(3, "Continuing without the audio server");
+        }
+    }
     // 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.
@@ -383,5 +407,33 @@ export async function run(packageDir, ctx, options) {
     const exec = spawnSync("docker", ["exec", "-it", "-w", workdir, containerName, "bash", "--login"], {
         stdio: "inherit",
     });
+    // --- Auto-stop host audio server (automatic mode, macOS) -----------------------------------------------------------------------------
+    // Control returns here synchronously when the user exits the shell. In automatic mode, stop the
+    // global host server only when no totopo session anywhere is still connected (the just-exited shell
+    // is already reaped, so 0 is the all-clear). Conservative by design: a lingering session keeps it up.
+    if (IS_MACOS && audio && readAudioMode() === AUDIO_MODE.automatic && isAudioServerRunning() && connectedSessionCount() === 0) {
+        const res = stopServer();
+        if (res.ok)
+            log.info("Host audio server stopped (no active sessions).");
+        else
+            log.warn(res.message);
+    }
+    // --- Offer to stop this workspace's container (last shell closed) --------------------------------------------------------------------
+    // The container itself keeps running (sleep infinity) after the shell exits. When this was the last
+    // shell to it, offer to stop it to free memory. Stop-only (no rm) so the next session resumes fast
+    // via the "exited" -> docker start path. Runs after the global audio auto-stop above; all platforms.
+    if (containerSessionCount(containerName) === 0) {
+        const stopNow = await confirm({
+            message: "Last session to this container closed. Stop it to free memory? (resumes fast next time)",
+            initialValue: true,
+        });
+        if (!isCancel(stopNow) && stopNow) {
+            log.step("Stopping container...");
+            spawnSync("docker", ["stop", containerName], { stdio: "pipe" });
+            log.info("Container stopped - memory freed; it resumes on your next session.");
+        }
+    }
+    // Trailing blank line so the last log does not sit flush against the next shell prompt.
+    process.stdout.write("\n");
     process.exit(exec.status ?? 0);
 }

package/dist/commands/doctor.js

@@ -7,13 +7,14 @@ import { spawnSync } from "node:child_process";
 import { log, outro } from "@clack/prompts";
 // Returns true if the given CLI tool is resolvable in the system PATH
 function commandExists(cmd) {
-    const r = spawnSync("command", ["-v", cmd], {
+    // Single command string (not an args array) under shell: true sidesteps Node's DEP0190; cmd is a hardcoded internal name.
+    const r = spawnSync(`command -v ${cmd}`, {
         shell: true,
         encoding: "utf8",
     });
     return r.status === 0;
 }
-export async function run(_workspaceDir, verbose) {
+export async function run(verbose) {
     const errors = [];
     function check(label, ok, detail) {
         if (ok) {

package/dist/commands/menu.js

@@ -6,20 +6,37 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { styleText } from "node:util";
 import { box, cancel, isCancel, select } from "@clack/prompts";
-import { PROFILE } from "../lib/constants.js";
-import { readActiveProfile } from "../lib/workspace-identity.js";
+import { IS_MACOS } from "../lib/audio-host.js";
+import { AUDIO_MODE, PROFILE } from "../lib/constants.js";
+import { readAudioMode } from "../lib/global-config.js";
+import { readActiveProfile, readAudio } from "../lib/workspace-identity.js";
 export async function run(args) {
     const { ctx, workspaceRunning, audioServerRunning, version } = args;
     // --- Read workspace config -----------------------------------------------------------------------------------------------------------
     const activeProfile = readActiveProfile(ctx.workspaceId) ?? PROFILE.default;
     const hasGit = existsSync(join(ctx.workspaceRoot, ".git"));
+    const audioWiring = readAudio(ctx.workspaceId);
     // --- Status box ----------------------------------------------------------------------------------------------------------------------
     const containerStatus = workspaceRunning ? "running" : "stopped";
     const gitNotice = hasGit ? "" : `\n${styleText("yellow", "●")} no git — agent changes are not tracked`;
-    // 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)`
-        : "";
+    // Surface the host audio server. When this workspace has voice wiring on, show its state at a glance
+    // (running / not running). When wiring is off but the global server happens to be up, still nudge the
+    // user to stop it - totopo never stops it on its own.
+    const audioRunning = `\n${styleText("yellow", "●")} audio server running (Settings › Voice / audio)`;
+    const audioStopped = `\n${styleText("gray", "●")} audio server not running (Settings › Voice / audio)`;
+    // In automatic mode (macOS) totopo starts the server when a session opens, so a "not running" notice
+    // is just noise - suppress it. In manual mode (or off macOS) the user starts it, so the nudge stays.
+    const autoStartsServer = IS_MACOS && readAudioMode() === AUDIO_MODE.automatic;
+    let audioNotice = "";
+    if (audioWiring) {
+        if (audioServerRunning)
+            audioNotice = audioRunning;
+        else if (!autoStartsServer)
+            audioNotice = audioStopped;
+    }
+    else if (audioServerRunning) {
+        audioNotice = audioRunning;
+    }
     box(`workspace:   ${ctx.workspaceId}\nprofile:     ${activeProfile}\ncontainer:   ${containerStatus}${gitNotice}${audioNotice}`, ` totopo v${version} `, {
         contentAlign: "left",
         titleAlign: "center",
@@ -29,8 +46,8 @@ export async function run(args) {
     const options = [
         { value: "dev", label: "Open session", hint: "start or resume the dev container" },
         ...(workspaceRunning ? [{ value: "stop", label: "Stop container", hint: "stops this workspace's container" }] : []),
-        { value: "settings", label: "Manage Workspace", hint: "shadow paths, rebuild, reset config" },
-        { value: "manage-totopo", label: "Manage totopo →", hint: "stop, clear, remove, uninstall" },
+        { value: "settings", label: "Settings", hint: "git mode, shadow paths, voice, rebuild" },
+        { value: "advanced", label: "Advanced", hint: "stop, clear, remove, uninstall" },
         { value: "help", label: "Help", hint: "official docs" },
         { value: "quit", label: "Quit" },
     ];

package/dist/commands/{workspace.js → settings.js}

@@ -1,11 +1,12 @@
 // =========================================================================================================================================
-// src/commands/workspace.ts - Manage Workspace submenu: shadow paths, rebuild, reset, stop, reset-image
+// src/commands/settings.ts - Settings submenu: git mode, shadow paths, voice, rebuild, reset config
 // =========================================================================================================================================
 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 { getStatus, IS_MACOS, installPulse, startServer, stopServer, testMic } from "../lib/audio-host.js";
-import { AUDIO_TCP_PORT, GIT_MODE } from "../lib/constants.js";
+import { AUDIO_MODE, AUDIO_TCP_PORT, GIT_MODE } from "../lib/constants.js";
+import { readAudioMode, writeAudioMode } from "../lib/global-config.js";
 import { countPatternHits } from "../lib/shadows.js";
 import { buildDefaultTotopoYaml, readTotopoYaml, writeTotopoYaml } from "../lib/totopo-yaml.js";
 import { readAudio, readGitMode, writeAudio, writeGitMode } from "../lib/workspace-identity.js";
@@ -166,10 +167,14 @@ async function gitModeMenu(ctx) {
 async function audioMenu(ctx) {
     while (true) {
         const wiring = readAudio(ctx.workspaceId);
+        const mode = readAudioMode();
         const status = getStatus();
         const serverLine = !status.installed ? "not installed" : status.running ? `running on TCP ${AUDIO_TCP_PORT}` : "installed, stopped";
+        // The server-control mode only matters where totopo manages the server (macOS).
+        const modeLine = IS_MACOS ? `\nmode:         ${mode}` : "";
         note(`wiring:       ${wiring ? "enabled" : "disabled"}  (this workspace)\n` +
             `host server:  ${serverLine}` +
+            modeLine +
             (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" +
@@ -182,6 +187,11 @@ async function audioMenu(ctx) {
             { value: "toggle", label: wiring ? "Disable wiring" : "Enable wiring", hint: "PulseAudio env for this workspace's container" },
         ];
         if (IS_MACOS) {
+            options.push({
+                value: "mode",
+                label: `Auto start/stop: ${mode === AUDIO_MODE.automatic ? "on" : "off"}`,
+                hint: "auto-start on session, stop on last exit",
+            });
             if (!status.installed)
                 options.push({ value: "install", label: "Install pulseaudio", hint: "via Homebrew" });
             if (status.installed && !status.running)
@@ -202,6 +212,16 @@ async function audioMenu(ctx) {
             await promptStopContainer(ctx);
             continue;
         }
+        if (action === "mode") {
+            // The host server is a single shared resource, so this mode is host-global. It only changes
+            // server lifecycle behavior, not container config, so no rebuild prompt.
+            const next = mode === AUDIO_MODE.automatic ? AUDIO_MODE.manual : AUDIO_MODE.automatic;
+            writeAudioMode(next);
+            log.success(next === AUDIO_MODE.automatic
+                ? "Automatic mode on - opening a session starts the host audio server; exiting stops it when no other session is connected."
+                : "Automatic mode off - start and stop the host audio server yourself.");
+            continue;
+        }
         let result;
         if (action === "install") {
             result = installPulse();
@@ -264,7 +284,7 @@ async function resetTotopoYaml(ctx) {
     log.success("totopo.yaml reset to defaults.");
     await promptStopContainer(ctx);
 }
-// --- Manage Workspace submenu ------------------------------------------------------------------------------------------------------------
+// --- Settings submenu --------------------------------------------------------------------------------------------------------------------
 export async function run(ctx) {
     while (true) {
         const currentGitMode = readGitMode(ctx.workspaceId) ?? GIT_MODE.local;
@@ -277,7 +297,7 @@ export async function run(ctx) {
             { value: "reset", label: "Reset config", hint: "restore totopo.yaml to defaults" },
             { value: "back", label: "← Back" },
         ];
-        const action = await select({ message: "Manage Workspace:", options });
+        const action = await select({ message: "Settings:", options });
         if (isCancel(action) || action === "back") {
             return "back";
         }

package/dist/lib/audio-host.js

@@ -8,7 +8,7 @@ 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";
+import { AUDIO_TCP_PORT, CONTAINER_NAME_PREFIX, GLOBAL_DIR, PULSE_COOKIE_FILE, 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
@@ -37,6 +37,34 @@ function pulseVersion() {
 export function isAudioServerRunning() {
     return spawnSync("pulseaudio", ["--check"], { stdio: "pipe" }).status === 0;
 }
+// Count live interactive sessions in a single container. dev.ts connects each with
+// `docker exec -it ... bash --login`, so a `bash --login` process is the proxy for one live session.
+// At exit the just-left shell is already reaped before this runs, so the last exit reaches 0.
+// Over-counting (e.g. an agent that spawns its own `bash --login`) only keeps things alive, which is
+// safe; a non-zero/errored `docker exec` (container gone) returns 0.
+export function containerSessionCount(containerName) {
+    const r = spawnSync("docker", ["exec", containerName, "pgrep", "-fc", "--", "bash --login"], { encoding: "utf8", stdio: "pipe" });
+    const n = Number.parseInt((r.stdout ?? "").trim(), 10);
+    return Number.isFinite(n) ? n : 0;
+}
+// Sum live interactive sessions across ALL totopo containers (delegates to containerSessionCount).
+// The host server is shared by every workspace, so automatic-mode auto-stop fires only at 0 - no
+// session anywhere. A hard-killed host process (SIGKILL / closed window) skips the exit check and
+// leaves the server running.
+export function connectedSessionCount() {
+    const ps = spawnSync("docker", ["ps", "--filter", `name=${CONTAINER_NAME_PREFIX}`, "--format", "{{.Names}}"], {
+        encoding: "utf8",
+        stdio: "pipe",
+    });
+    if (ps.status !== 0)
+        return 0;
+    const names = (ps.stdout ?? "").trim().split("\n").filter(Boolean);
+    let total = 0;
+    for (const name of names) {
+        total += containerSessionCount(name);
+    }
+    return total;
+}
 // --- Status ------------------------------------------------------------------------------------------------------------------------------
 // Snapshot of the host audio server for the Voice menu.
 export function getStatus() {
@@ -62,10 +90,11 @@ export function installPulse() {
 // 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
+// PulseAudio cookie and never mounting that general credential into the container. It lives under the
+// host-global ~/.totopo/global/ dir (the server is a single shared resource, not per-workspace) 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");
+    return join(homedir(), TOTOPO_DIR, GLOBAL_DIR, PULSE_COOKIE_FILE);
 }
 // 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.

package/dist/lib/constants.js

@@ -10,6 +10,7 @@ export const PACKAGE_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.ur
 export const TOTOPO_DIR = ".totopo";
 export const WORKSPACES_DIR = "workspaces";
 export const PROJECTS_DIR = "projects"; // legacy v3-rc-1/rc-2; only referenced in migration
+export const GLOBAL_DIR = "global"; // host-global state not tied to a workspace (config + pulse cookie)
 // Workspace cache subdirectories (under ~/.totopo/workspaces/<id>/)
 export const AGENTS_DIR = "agents";
 export const SHADOWS_DIR = "shadows";
@@ -18,6 +19,8 @@ export const PNPM_STORE_DIR = "pnpm-store";
 export const TOTOPO_YAML = "totopo.yaml";
 export const LOCK_FILE = ".lock";
 export const GLOBAL_ENV_FILE = ".env"; // legacy global key file; only referenced in migration
+export const GLOBAL_CONFIG_FILE = "config"; // ~/.totopo/global/config - key=value host-global settings
+export const PULSE_COOKIE_FILE = "pulse-cookie"; // ~/.totopo/global/pulse-cookie - dedicated PulseAudio TCP cookie
 // Workspace ID constraints (must match schema/totopo.schema.json)
 export const WORKSPACE_ID_MIN = 2;
 export const WORKSPACE_ID_MAX = 48;
@@ -73,3 +76,10 @@ 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`;
+// Host audio server control mode (host-global, stored in ~/.totopo/global/config). manual: the user starts and stops
+// the host server from the Voice/audio menu. automatic: totopo starts it when a session opens and stops
+// it when the last connected session exits. Automation is macOS-only (the platform where totopo manages
+// PulseAudio), so automatic mode is offered only there. Defaults to manual. Defined directly here (unlike
+// GIT_MODE) because there is no container-side consumer that would need runtime-constants.mjs.
+export const AUDIO_MODE = { manual: "manual", automatic: "automatic" };
+export const AUDIO_MODES = Object.values(AUDIO_MODE);

package/dist/lib/global-config.js

@@ -0,0 +1,63 @@
+// =========================================================================================================================================
+// src/lib/global-config.ts - Host-global settings store (not tied to any workspace)
+// Lives at ~/.totopo/global/config as key=value lines, mirroring the per-workspace .lock idiom.
+// The host audio server is a single shared resource, so its control mode is global, not per-workspace.
+// =========================================================================================================================================
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { AUDIO_MODE, AUDIO_MODES, GLOBAL_CONFIG_FILE, GLOBAL_DIR, TOTOPO_DIR } from "./constants.js";
+// --- Keys --------------------------------------------------------------------------------------------------------------------------------
+/** Field names mapped to the keys written in the global config file. */
+export const GLOBAL_CONFIG_KEYS = {
+    audioMode: "audio_mode",
+};
+// --- Path --------------------------------------------------------------------------------------------------------------------------------
+/** Absolute path to the global config file - ~/.totopo/global/config */
+export function globalConfigPath() {
+    return join(homedir(), TOTOPO_DIR, GLOBAL_DIR, GLOBAL_CONFIG_FILE);
+}
+// --- Parse / write -----------------------------------------------------------------------------------------------------------------------
+// Parse the config into an ordered map of raw key=value pairs. Returns an empty map when the file is
+// missing or unreadable - absence is not an error, it just means defaults apply. Unknown keys are kept
+// so a newer totopo's settings survive a write by an older one.
+function parseGlobalConfig() {
+    const config = new Map();
+    try {
+        const lines = readFileSync(globalConfigPath(), "utf8")
+            .trimEnd()
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+        for (const line of lines) {
+            const eq = line.indexOf("=");
+            if (eq === -1)
+                continue;
+            config.set(line.slice(0, eq), line.slice(eq + 1));
+        }
+    }
+    catch {
+        // Missing or unreadable - treat as empty.
+    }
+    return config;
+}
+// Write the raw key=value map back to ~/.totopo/global/config, creating ~/.totopo/global/ on demand.
+// Unlike the per-workspace lock (which no-ops when missing), the global config has no init step, so it
+// is created lazily on the first write.
+function writeGlobalConfig(config) {
+    mkdirSync(join(homedir(), TOTOPO_DIR, GLOBAL_DIR), { recursive: true });
+    const content = `${[...config].map(([key, value]) => `${key}=${value}`).join("\n")}\n`;
+    writeFileSync(globalConfigPath(), content);
+}
+// --- Audio mode --------------------------------------------------------------------------------------------------------------------------
+/** Read the host audio server control mode. Defaults to manual when unset, missing, or unrecognized. */
+export function readAudioMode() {
+    const value = parseGlobalConfig().get(GLOBAL_CONFIG_KEYS.audioMode);
+    return value !== undefined && AUDIO_MODES.includes(value) ? value : AUDIO_MODE.manual;
+}
+/** Write the host audio server control mode. Creates the config file on demand and preserves all other keys. */
+export function writeAudioMode(audioMode) {
+    const config = parseGlobalConfig();
+    config.set(GLOBAL_CONFIG_KEYS.audioMode, audioMode);
+    writeGlobalConfig(config);
+}

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

@@ -27,7 +27,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { confirm, isCancel, log, note } from "@clack/prompts";
 import { load as loadYaml } from "js-yaml";
-import { AGENTS_DIR, GIT_MODE, LABEL_BUILD_HASH, LOCK_FILE, PROFILE, SHADOWS_DIR, TOTOPO_DIR, TOTOPO_YAML, WORKSPACES_DIR, } from "./constants.js";
+import { AGENTS_DIR, CONTAINER_NAME_PREFIX, GIT_MODE, GLOBAL_DIR, LABEL_BUILD_HASH, LOCK_FILE, PROFILE, PULSE_COOKIE_FILE, SHADOWS_DIR, TOTOPO_DIR, TOTOPO_YAML, WORKSPACES_DIR, } from "./constants.js";
 import { safeRmSync } from "./safe-rm.js";
 import { buildDefaultTotopoYaml, readTotopoYaml, slugifyForWorkspaceId, validateWorkspaceId, writeTotopoYaml, } from "./totopo-yaml.js";
 import { findTotopoYamlDir, getWorkspacesBaseDir, initWorkspaceDir, LOCK_KEYS } from "./workspace-identity.js";
@@ -417,7 +417,7 @@ export function migrateAddGitMode() {
         }
     }
     if (migrated > 0) {
-        note(`totopo v3.4.0 introduces git modes for workspaces.\nDefault is 'local' (previous behavior — local commits allowed, remote blocked).\nTwo opt-in modes are available: 'strict' (read-only, all mutations blocked) and 'unrestricted' (no totopo-enforced restrictions).\nSwitch via the totopo menu > Manage Workspace > Git mode.`, "Git modes");
+        note(`totopo v3.4.0 introduces git modes for workspaces.\nDefault is 'local' (previous behavior — local commits allowed, remote blocked).\nTwo opt-in modes are available: 'strict' (read-only, all mutations blocked) and 'unrestricted' (no totopo-enforced restrictions).\nSwitch via the totopo menu > Settings > Git mode.`, "Git modes");
     }
     return migrated;
 }
@@ -449,10 +449,58 @@ export function migrateAddAudio() {
         }
     }
     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");
+        note(`totopo v3.9.0 adds opt-in microphone support for Claude Code's /voice.\nEnable it per workspace via the totopo menu > Settings > 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;
 }
+/**
+ * Pre-v3.10.0 -> latest: Move the dedicated PulseAudio cookie from ~/.totopo/pulse-cookie into the new
+ * host-global ~/.totopo/global/ dir. The cookie is live bind-mounted into running containers, so it is
+ * never moved while a container could hold it open: if any totopo container is running we ask to stop
+ * them first (interactive) or defer to the next run (non-interactive). Most users never enabled audio
+ * and so have no cookie - for them this is a no-op. Idempotent: once moved, the source is gone.
+ */
+async function migrateMoveAudioCookie(interactive) {
+    // A path (source): hardcode the literal so the migration still finds the old location later.
+    const oldPath = join(homedir(), ".totopo", "pulse-cookie");
+    if (!existsSync(oldPath))
+        return;
+    const globalDir = join(homedir(), TOTOPO_DIR, GLOBAL_DIR);
+    const newPath = join(globalDir, PULSE_COOKIE_FILE);
+    // The cookie is live-mounted into running containers; never move it out from under one. A failed or
+    // absent docker means nothing can be running, so treat that as zero containers.
+    const ps = spawnSync("docker", ["ps", "--filter", `name=${CONTAINER_NAME_PREFIX}`, "--format", "{{.Names}}"], {
+        encoding: "utf8",
+        stdio: "pipe",
+    });
+    const running = ps.status === 0 ? (ps.stdout ?? "").trim().split("\n").filter(Boolean) : [];
+    if (running.length > 0) {
+        if (!interactive)
+            return; // Defer - re-runs next startup when confirmations are allowed.
+        log.warn(`The audio cookie is moving to ~/.totopo/global/, but ${running.length} totopo container(s) are using it.\n` +
+            "  They must be stopped so the cookie can move cleanly (they are recreated on next session).");
+        const shouldStop = await confirm({ message: "Stop running totopo containers to migrate the audio cookie?", initialValue: true });
+        if (isCancel(shouldStop) || !shouldStop) {
+            log.info("Kept containers running - the audio cookie will migrate on next run.");
+            return;
+        }
+        for (const name of running) {
+            spawnSync("docker", ["stop", name], { stdio: "pipe" });
+            spawnSync("docker", ["rm", name], { stdio: "pipe" });
+        }
+        log.info("Containers stopped - they will be recreated on next session.");
+    }
+    // Nothing is mounting the cookie now, so move it once. If a cookie already exists at the destination
+    // (e.g. the server cold-started since), the destination is authoritative - drop the stale source.
+    mkdirSync(globalDir, { recursive: true });
+    if (existsSync(newPath)) {
+        safeRmSync(oldPath);
+    }
+    else {
+        renameSync(oldPath, newPath);
+    }
+    note("totopo now keeps audio settings and the PulseAudio cookie in ~/.totopo/global/.\nOn macOS it can start and stop the host audio server for you - see the totopo menu > Settings > Voice / audio.", "Voice / audio");
+}
 /**
  * v3.2.1 and earlier: Remove deprecated fields from totopo.yaml.
  * - schema_version: redundant, totopo validates with the bundled JSON schema at runtime
@@ -526,6 +574,11 @@ function buildMigrations(cwd, skipAnyConfirmations) {
         },
         { 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 },
+        {
+            from: "v3.10.0",
+            description: "Move pulse cookie to ~/.totopo/global/",
+            run: () => migrateMoveAudioCookie(!skipAnyConfirmations),
+        },
     ];
 }
 /** Run all migrations in order. Called early in bin/totopo.js startup. */

package/package.json

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

package/templates/context/responsibilities.md

@@ -2,4 +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.
+- 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 **Settings -> Voice / audio** — not from inside the container.

package/templates/git-readonly-wrapper.mjs

@@ -281,7 +281,7 @@ function firstNonFlag(args) {
 function blocked(label) {
     return {
         allow: false,
-        reason: `git: '${label}' blocked in strict mode (read-only). Switch git mode via 'totopo' menu > Manage Workspace > Git mode.`,
+        reason: `git: '${label}' blocked in strict mode (read-only). Switch git mode via 'totopo' menu > Settings > Git mode.`,
     };
 }