totopo 3.6.0 → 3.7.0-rc-1

package/README.md

@@ -10,6 +10,12 @@ Local sandbox for AI agents.
 ![npm downloads](https://img.shields.io/npm/dm/totopo)
 ![license](https://img.shields.io/npm/l/totopo)
 
+## Who this is for
+
+Developers who use `claude`, `codex`, or `opencode` **interactively** — one human pair-programming with one agent.
+
+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
 
 Two fundamental risks when running AI agents locally:
@@ -21,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
@@ -50,7 +54,7 @@ A few things happen automatically:
 
 - **Agents stay up to date** — totopo keeps all AI CLIs on their latest versions, checking for updates automatically.
 - **Sessions are persistent** — agent memory and settings survive container restarts and rebuilds.
-- **Your machine stays safe** — the container can't push to remote, can't read outside the workspace, and sensitive paths like `.env` can be hidden from agents entirely (see [Shadow Paths](#shadow-paths)).
+- **The blast radius is bounded** — the container can't push to remote or read outside the workspace, and you can hide files like `.env` from the agent (see [Shadow Paths](#shadow-paths)). For what this does and doesn't protect against, see [Threat Model](#threat-model).
 
 For a deeper look at how totopo works and how to configure it, see the sections below.
 
@@ -160,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.
@@ -250,6 +256,20 @@ To clear memory: `npx totopo` → **Manage totopo > Clear agent memory**.
 }
 ```
 
+## Threat Model
+
+Totopo makes everyday agent mistakes safer. It is not built to stop a determined attacker.
+
+**What it helps with:**
+- Confused-agent mistakes — only the workspace is at risk; the rest of your machine is invisible.
+- Casual prompt injection — the agent can't read your SSH keys or push to your remote, because neither is in the container.
+
+**What it does not help with:**
+- A determined adversarial agent. The network is open, and `/usr/bin/git` is reachable by absolute path even in strict mode. Anything in the workspace can still leave over HTTP.
+- Secrets you didn't shadow. A `.env` tracked in git is visible unless you list it in `shadow_paths`.
+- 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.
+
 ## Disclaimer
 
 MIT licensed and fully open source. Issues welcome — no promises on response time. Use at your own risk.

package/dist/commands/dev.js

@@ -263,10 +263,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/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" });

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totopo",
-  "version": "3.6.0",
+  "version": "3.7.0-rc-1",
   "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.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 -----------------------------------------------------------------