totopo 3.6.1 → 3.7.0-rc-2

package/README.md

@@ -14,7 +14,7 @@ Local sandbox for AI agents.
 
 Developers who use `claude`, `codex`, or `opencode` **interactively** — one human pair-programming with one agent.
 
-totopo is not an orchestration tool — no SDK, no parallel agents, no per-run worktrees. If you need those, look at dedicated agent-orchestration tools instead.
+totopo isn't an orchestration tool (no SDK, no parallel agents, no per-run worktrees), and its security is basic — just the minimum precautions I think anyone running AI agents should take. If you need more on either front, look elsewhere.
 
 ## Motivation
 
@@ -27,8 +27,6 @@ Totopo mitigates both risks by letting you run agents in a dev container — whe
 
 In practice, this means any mistake can be reverted from your git remote, and even a compromised agent can't access sensitive files on your machine — SSH keys, credentials, browser data — things a locally-running agent could otherwise do without you ever noticing.
 
-> totopo's security approach is basic — it is about the minimal precautions I believe anyone running AI agents should have. If you need more robust protections, look somewhere else.
-
 ## Requirements
 
 - [Docker](https://www.docker.com/products/docker-desktop/) — builds and runs the dev container
@@ -166,6 +164,8 @@ shadow_paths:
 
 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.
 
+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.
+
 Common use cases:
 - **Separate `node_modules`** — the container installs its own dependencies, avoiding platform conflicts between host and container.
 - **Hide sensitive files** — keep credentials and secrets invisible to agents.

package/dist/commands/dev.js

@@ -103,7 +103,10 @@ function stopAndRemoveContainer(containerName) {
 }
 // --- Run startup checks (AI CLI update + readiness validation) ---------------------------------------------------------------------------
 function runStartup(containerName, quiet) {
-    const result = spawnSync("docker", ["exec", "-u", "root", containerName, "node", CONTAINER_STARTUP], {
+    // The SPACE-to-skip prompt in startup.mjs needs raw-mode stdin (-i) and a PTY (-t).
+    // Omitted when quiet so test output stays pipe-capturable.
+    const ttyFlags = quiet ? [] : ["-i", "-t"];
+    const result = spawnSync("docker", ["exec", "-u", "root", ...ttyFlags, containerName, "node", CONTAINER_STARTUP], {
         stdio: quiet ? "pipe" : "inherit",
     });
     return result.status === 0;
@@ -263,10 +266,13 @@ export async function run(packageDir, ctx, options) {
     const profileHook = profileConfig?.dockerfile_hook;
     // --- Shadow path expansion -----------------------------------------------------------------------------------------------------------
     const shadowPatterns = yaml.shadow_paths ?? [];
-    const expandedShadows = expandShadowPatterns(shadowPatterns, workspaceDir);
+    const { paths: expandedShadows, skippedTracked } = expandShadowPatterns(shadowPatterns, workspaceDir);
     if (expandedShadows.length > 0) {
         log.warn(`Shadow paths active: ${expandedShadows.join(", ")}  (Settings > Shadow paths)`);
     }
+    if (skippedTracked.length > 0) {
+        log.warn(`Skipped ${skippedTracked.length} shadow path(s) tracked by git`);
+    }
     // --- Env file ------------------------------------------------------------------------------------------------------------------------
     let envFilePath;
     if (yaml.env_file) {

package/dist/commands/onboard.js

@@ -121,7 +121,7 @@ export async function run(cwd) {
         const workspaceId = deriveUniqueWorkspaceId(inputId, workspaceRoot);
         // Build and write totopo.yaml
         yaml = buildDefaultTotopoYaml(workspaceId);
-        writeTotopoYaml(workspaceRoot, yaml);
+        writeTotopoYaml(workspaceRoot, yaml, { includeExtendedTemplate: true });
         log.success(`Created ${toTildePath(join(workspaceRoot, TOTOPO_YAML))}`);
     }
     // --- Non-git warning -----------------------------------------------------------------------------------------------------------------

package/dist/commands/workspace.js

@@ -28,7 +28,8 @@ async function shadowPathsMenu(ctx) {
     }
     log.message("Shadow patterns block the agent from seeing matching host paths —\n" +
         "the container gets an empty, isolated copy instead.\n" +
-        "Supports gitignore-style patterns (e.g. node_modules, .env*).");
+        "Supports gitignore-style patterns (e.g. node_modules, .env*).\n" +
+        "Git-tracked paths are skipped to avoid worktree diversions.");
     const options = [{ value: "add", label: "Add pattern or path" }];
     if (patterns.length > 0) {
         options.push({ value: "remove", label: "Remove patterns" });
@@ -196,7 +197,7 @@ async function resetTotopoYaml(ctx) {
     if (isCancel(confirmed) || !confirmed)
         return;
     const freshYaml = buildDefaultTotopoYaml(yaml.workspace_id);
-    writeTotopoYaml(ctx.workspaceRoot, freshYaml);
+    writeTotopoYaml(ctx.workspaceRoot, freshYaml, { includeExtendedTemplate: true });
     log.success("totopo.yaml reset to defaults.");
     await promptStopContainer(ctx);
 }

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

@@ -119,7 +119,7 @@ function migrateSingleV2Workspace(v2, existingIds) {
         if (v2.shadowPaths.length > 0) {
             yaml.shadow_paths = [...new Set([...(yaml.shadow_paths ?? []), ...v2.shadowPaths])];
         }
-        writeTotopoYaml(v2.projectRoot, yaml);
+        writeTotopoYaml(v2.projectRoot, yaml, { includeExtendedTemplate: true });
         log.info(`Created totopo.yaml for "${v2.displayName}" (workspace_id: ${workspaceId})`);
     }
     const newDir = join(getWorkspacesBaseDir(), workspaceId);

package/dist/lib/shadows.js

@@ -2,22 +2,26 @@
 // src/lib/shadows.ts - Gitignore-style shadow path expansion and sync
 // Expands patterns like "node_modules", ".env*" into concrete paths, then syncs shadow directories.
 // =========================================================================================================================================
+import { spawnSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import fg from "fast-glob";
 import { CONTAINER_WORKSPACE, SHADOWS_DIR } from "./constants.js";
 import { safeRmSync } from "./safe-rm.js";
-// --- Pattern expansion -------------------------------------------------------------------------------------------------------------------
 /**
  * Expand gitignore-style patterns into concrete relative paths.
  *
  * Patterns without a directory separator are treated as recursive (prepended with **/)
  * following gitignore convention. Patterns with a / are matched relative to the workspace root.
  * Matched directories are not recursed into (e.g. node_modules matches once, not its children).
+ *
+ * Paths that git tracks (or whose descendants git tracks) are dropped from the result and
+ * reported in skippedTracked. Shadowing tracked content is a no-op (agents can `git show` it)
+ * and breaks `git stash`/`pop` workflows.
  */
 export function expandShadowPatterns(patterns, workspaceRoot) {
     if (patterns.length === 0)
-        return [];
+        return { paths: [], skippedTracked: [] };
     // Convert gitignore-style patterns to fast-glob patterns
     const globPatterns = patterns.map((p) => (p.includes("/") ? p : `**/${p}`));
     // Build ignore list: skip .git and contents of any matched directory
@@ -28,12 +32,51 @@ export function expandShadowPatterns(patterns, workspaceRoot) {
         dot: true,
         ignore: ignorePatterns,
     });
-    return removeNestedPaths(results.sort());
+    const expanded = removeNestedPaths(results.sort());
+    const { kept, dropped } = filterGitTrackedPaths(expanded, workspaceRoot);
+    return { paths: kept, skippedTracked: dropped };
 }
 // --- Hit counting (for menu UX) ----------------------------------------------------------------------------------------------------------
-/** Count how many paths a pattern would match in the workspace. */
+/** Count how many paths a pattern would match in the workspace (post git-tracked filter). */
 export function countPatternHits(pattern, workspaceRoot) {
-    return expandShadowPatterns([pattern], workspaceRoot).length;
+    return expandShadowPatterns([pattern], workspaceRoot).paths.length;
+}
+// --- Git-tracked filtering ---------------------------------------------------------------------------------------------------------------
+/**
+ * Partition expanded shadow paths into those safe to shadow and those tracked by git.
+ * A path is dropped if it equals a tracked file, or (for directories) any tracked file
+ * lives anywhere beneath it. Returns the input unchanged when no .git is present.
+ */
+function filterGitTrackedPaths(paths, workspaceRoot) {
+    if (paths.length === 0)
+        return { kept: [], dropped: [] };
+    // .git may be a file (worktrees) or a directory; existsSync handles both
+    if (!existsSync(join(workspaceRoot, ".git")))
+        return { kept: paths, dropped: [] };
+    // Pass shadow paths as pathspecs so git enumerates only tracked files within them.
+    // Output then scales with shadow scope (typically tiny), not the size of the repo index.
+    const result = spawnSync("git", ["-C", workspaceRoot, "ls-files", "-z", "--", ...paths], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.status !== 0)
+        return { kept: paths, dropped: [] };
+    const matched = result.stdout.split("\0").filter((s) => s.length > 0);
+    if (matched.length === 0)
+        return { kept: paths, dropped: [] };
+    const matchedSet = new Set(matched);
+    const kept = [];
+    const dropped = [];
+    for (const p of paths) {
+        const prefix = `${p}/`;
+        if (matchedSet.has(p) || matched.some((f) => f.startsWith(prefix))) {
+            dropped.push(p);
+        }
+        else {
+            kept.push(p);
+        }
+    }
+    return { kept, dropped };
 }
 // --- Shadow sync -------------------------------------------------------------------------------------------------------------------------
 /**

package/dist/lib/totopo-yaml.js

@@ -89,7 +89,7 @@ const YAML_COMMENTS = {
         "# When multiple profiles exist, totopo prompts you to pick one on session start.",
 };
 /** Write totopo.yaml to a directory with schema header and inline comments. */
-export function writeTotopoYaml(dir, config) {
+export function writeTotopoYaml(dir, config, opts = {}) {
     const filePath = join(dir, TOTOPO_YAML);
     const yamlContent = dumpYaml(config, {
         lineWidth: -1,
@@ -109,11 +109,14 @@ export function writeTotopoYaml(dir, config) {
         output.push(line);
     }
     const body = output.join("\n").trimEnd();
-    writeFileSync(filePath, `${body}\n${PROFILES_FOOTER_COMMENT}\n`);
+    const extendedBlock = opts.includeExtendedTemplate ? `\n\n${EXTENDED_PROFILE_TEMPLATE_PROMPT}\n${renderExtendedAsCommented()}` : "";
+    writeFileSync(filePath, `${body}${extendedBlock}\n${PROFILES_FOOTER_COMMENT}\n`);
 }
 // --- Defaults ----------------------------------------------------------------------------------------------------------------------------
+const DEFAULT_PROFILE_DESCRIPTION = "Base image: Node.js, git, and AI CLIs";
 const DEFAULT_PROFILE_HOOK = `# No extras — uses the totopo base image as-is (Node.js + git + AI CLIs).
 `;
+const EXTENDED_PROFILE_DESCRIPTION = "Base image + Go, Java, Rust, and Bun";
 const EXTENDED_PROFILE_HOOK = `# Go
 RUN apt-get update && apt-get install -y --no-install-recommends golang-go && rm -rf /var/lib/apt/lists/*
 
@@ -133,6 +136,20 @@ RUN curl -fsSL https://bun.sh/install | bash
 `;
 // Appended after the last profile to hint at adding more
 const PROFILES_FOOTER_COMMENT = "  # Add more profiles here — or ask the agent inside the container to set one up for you.";
+const EXTENDED_PROFILE_TEMPLATE_PROMPT = "  # Uncomment to enable additional runtimes (Go, Java, Rust, Bun):";
+/**
+ * Render the `extended` profile as commented-out YAML, indented to live under `profiles:`.
+ * Generated via the same dumpYaml call as the live config so uncommenting (strip leading `# `
+ * from each line) yields YAML the parser/schema accepts without drift.
+ */
+function renderExtendedAsCommented() {
+    const dumped = dumpYaml({ extended: { description: EXTENDED_PROFILE_DESCRIPTION, dockerfile_hook: EXTENDED_PROFILE_HOOK } }, { lineWidth: -1, quotingType: '"', forceQuotes: false });
+    return dumped
+        .split("\n")
+        .map((line) => (line.length === 0 ? "" : `  # ${line}`))
+        .join("\n")
+        .trimEnd();
+}
 /** Create a default TotopoYamlConfig with sane defaults. */
 export function buildDefaultTotopoYaml(workspaceId) {
     return {
@@ -141,13 +158,9 @@ export function buildDefaultTotopoYaml(workspaceId) {
         shadow_paths: [...DEFAULT_SHADOW_PATHS],
         profiles: {
             default: {
-                description: "Base image: Node.js, git, and AI CLIs",
+                description: DEFAULT_PROFILE_DESCRIPTION,
                 dockerfile_hook: DEFAULT_PROFILE_HOOK,
             },
-            extended: {
-                description: "Base image + Go, Java, Rust, and Bun",
-                dockerfile_hook: EXTENDED_PROFILE_HOOK,
-            },
         },
     };
 }
@@ -201,7 +214,7 @@ export function repairTotopoYaml(dir) {
             return { repairedYaml: null, error: `${TOTOPO_YAML} could not be repaired: ${formatValidationErrors(validate.errors)}` };
         }
         const yaml = obj;
-        writeTotopoYaml(dir, yaml);
+        writeTotopoYaml(dir, yaml, { includeExtendedTemplate: fixes.includes("added default profiles") });
         return { repairedYaml: yaml, message: `Repaired ${TOTOPO_YAML}: ${fixes.join(", ")}` };
     }
     catch (err) {

package/package.json

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

package/templates/context/git-mode-local.md

@@ -1,8 +1,6 @@
 ## Git availability
 
-The user set git mode to **local** in totopo.
-
-Please respect this choice — do not attempt remote git operations (push, pull, fetch, clone).
+The user set git mode to **local** in totopo - do not attempt remote git operations (push, pull, fetch, clone).
 
 totopo enforces this by:
 - Blocking remote access (push, pull, fetch, clone).

package/templates/context/git-mode-strict.md

@@ -1,8 +1,6 @@
 ## Git availability
 
-The user set git mode to **strict** in totopo.
-
-Please respect this choice — do not attempt git operations that modify state or interact with remotes.
+The user set git mode to **strict** in totopo — do not attempt git operations that modify state or interact with remotes.
 
 totopo enforces this by:
 - Blocking git commands that would modify the repository (attempts return a clear error).

package/templates/context/git-mode-unrestricted.md

@@ -1,3 +1,3 @@
 ## Git availability
 
-The user set git mode to **unrestricted** in totopo. totopo does not enforce any git-specific restrictions in this mode; git operations are subject only to git's own behavior and to any credentials configured in the container.
+The user set git mode to **unrestricted** in totopo. totopo does not enforce any git-specific restrictions in this mode.

package/templates/context/git-unavailable.md

@@ -1,5 +1,5 @@
 ## Git availability
 
-Git is **not available** — no `.git` directory was found in the workspace root.
+Git is not available — no `.git` directory was found in the workspace root.
 
 If git operations are needed, ask the user to run them on the host.

package/templates/context/responsibilities.md

@@ -1,4 +1,4 @@
 ## Your responsibilities at session start
 
 At the start of every session:
-- Briefly tell the user they are in a totopo sandbox and mention key limitations (git remote block, no host filesystem access outside the workspace).
+- Briefly tell the user they are in a totopo sandbox and mention key limitations (totopo git mode, no host filesystem access outside the workspace).

package/templates/context/shadow-paths.md

@@ -1,7 +1,6 @@
 ## Shadow paths
 
-The following patterns are overlaid with container-local storage and do not reflect
-the host filesystem:
+The following patterns are overlaid with container-local storage and do not reflect the host filesystem:
 
 {{pattern_list}}
 
@@ -9,3 +8,5 @@ Matching paths are initialized empty on first use. The container may accumulate
 content in them over time (for example, a shadowed `node_modules` gets
 populated when you run `npm install` inside the container). Do not assume they
 are empty, and do not attempt to sync or restore their host contents.
+
+Git-tracked paths are skipped to avoid worktree diversions.

package/templates/context/workspace.md

@@ -1,3 +1,3 @@
 ## Workspace
 
-You have access to the full workspace directory at `/workspace`. Some operations (git push, system-level changes) require running on the host.
+You have access to the full workspace directory at `/workspace`. Some operations may require running on the host.

package/templates/startup-git-mode.mjs

@@ -45,8 +45,10 @@ function removeWrapperIfPresent() {
 }
 
 function applyAsRoot(gitMode, protocolValue, fail) {
+    // Use absolute path to bypass /usr/local/bin/git (which may already be the read-only
+    // wrapper from a prior strict-mode session and would block this legitimate setup write).
     try {
-        execSync(`git config --system protocol.allow ${protocolValue}`, { stdio: "pipe" });
+        execSync(`/usr/bin/git config --system protocol.allow ${protocolValue}`, { stdio: "pipe" });
     } catch {
         fail("git mode", `failed to set protocol.allow=${protocolValue}`);
     }

package/templates/startup.mjs

@@ -51,19 +51,17 @@ const TIMESTAMP_FILE = "/home/devuser/.ai-cli-updated";
 const THROTTLE_MS = 24 * 60 * 60 * 1000;
 
 let lastUpdate = 0;
+let timestampFileExists = false;
 try {
     const raw = readFileSync(TIMESTAMP_FILE, "utf8").trim();
     lastUpdate = new Date(raw).getTime();
+    timestampFileExists = true;
 } catch {
     // File missing or unreadable -- treat as never updated
 }
 
-if (Number.isFinite(lastUpdate) && Date.now() - lastUpdate < THROTTLE_MS) {
-    ok("AI CLIs", "up to date");
-} else if (!isRoot) {
-    skip("AI CLIs", "update skipped (requires root)");
-} else {
-    console.log(`${blue("●")} ${dim("Updating AI CLIs to latest...")}`);
+const doUpdate = (label) => {
+    console.log(`${blue("●")} ${dim(label)}`);
     try {
         execSync("npm install -g opencode-ai@latest @anthropic-ai/claude-code@latest @openai/codex@latest", {
             stdio: "inherit",
@@ -73,6 +71,64 @@ if (Number.isFinite(lastUpdate) && Date.now() - lastUpdate < THROTTLE_MS) {
     } catch {
         fail("AI CLIs", "update failed -- continuing with existing versions");
     }
+};
+
+// SPACE within `seconds` -> skip. Any other input is ignored. Ctrl+C exits 130. Non-TTY -> no skip.
+const promptSkipUpdate = (seconds) =>
+    new Promise((resolve) => {
+        if (!process.stdin.isTTY) {
+            resolve(false);
+            return;
+        }
+        let remaining = seconds;
+        let tick;
+        let timer;
+        const line = (s) => `\r\x1b[K${blue("●")} ${dim(`Updating AI CLIs in ${s}s... press SPACE to skip`)}`;
+        const cleanup = () => {
+            clearInterval(tick);
+            clearTimeout(timer);
+            process.stdin.removeListener("data", onData);
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+            process.stdout.write("\r\x1b[K");
+        };
+        const onData = (chunk) => {
+            for (const byte of chunk) {
+                if (byte === 0x03) {
+                    cleanup();
+                    process.exit(130);
+                }
+                if (byte === 0x20) {
+                    cleanup();
+                    resolve(true);
+                    return;
+                }
+            }
+        };
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on("data", onData);
+        process.stdout.write(line(remaining));
+        tick = setInterval(() => {
+            remaining -= 1;
+            if (remaining > 0) process.stdout.write(line(remaining));
+        }, 1000);
+        timer = setTimeout(() => {
+            cleanup();
+            resolve(false);
+        }, seconds * 1000);
+    });
+
+if (Number.isFinite(lastUpdate) && Date.now() - lastUpdate < THROTTLE_MS) {
+    ok("AI CLIs", "up to date");
+} else if (!isRoot) {
+    skip("AI CLIs", "update skipped (requires root)");
+} else if (!timestampFileExists) {
+    doUpdate("Installing AI CLIs...");
+} else if (await promptSkipUpdate(5)) {
+    skip("AI CLIs", "update skipped by user");
+} else {
+    doUpdate("Updating AI CLIs to latest...");
 }
 
 // -- Security -----------------------------------------------------------------