totopo 3.3.3 → 3.4.0-rc-1

package/README.md

@@ -77,7 +77,7 @@ 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** — shadow paths, rebuild, reset config
+- **Manage Workspace** — git mode, shadow paths, rebuild, reset config
 - **Manage totopo** — multi-workspace management (stop containers, clear memory, uninstall)
 
 ### Working directory
@@ -96,11 +96,21 @@ Every session runs inside a Docker container. Your code is bind-mounted from the
 | No host credentials | Host git credentials are never copied into the container |
 | No privilege escalation | `no-new-privileges:true` prevents any process from gaining elevated permissions |
 | Filesystem isolation | Only the workspace directory is mounted; the rest of the host is not visible |
-| Git remote block | `protocol.allow = never` in `/etc/gitconfig` — push, pull, fetch, and clone are refused |
+| Git guardrails | Per-workspace **git mode** controls what git can do inside the container — see [Git Modes](#git-modes) |
 | Shadow mounts | Selected paths overlaid with isolated container-local copies — see [Shadow Paths](#shadow-paths) |
 | Environment vars | Injected from a host file at session start (`env_file`) |
 
-Remote git operations are blocked inside the container. Run them from your host terminal.
+### Git Modes
+
+Each workspace has a git mode (set via **Manage Workspace > Git mode**) that controls what git operations are permitted inside the container:
+
+| Mode | Local mutations | Remote (push/pull/fetch/clone) |
+|---|---|---|
+| **strict** *(default for new workspaces)* | Blocked — a read-only `git` wrapper allows inspection (`status`, `log`, `diff`, `blame`, `show`, etc.) and rejects mutations (`commit`, `add`, `reset`, `checkout`, etc.) | Blocked at the gitconfig protocol layer |
+| **local** *(default for workspaces upgraded from earlier versions)* | Allowed | Blocked at the gitconfig protocol layer |
+| **unrestricted** | Allowed | Allowed — totopo enforces no git-specific restrictions |
+
+The active mode is recorded per workspace in `.lock`, exposed inside the container as `TOTOPO_GIT_MODE`, and reflected in the agent context so each session knows what is permitted. Switching modes recreates the container on the next session.
 
 ### Profiles
 
@@ -203,7 +213,7 @@ To clear memory: `npx totopo` → **Manage totopo > Clear agent memory**.
 ~/.totopo/
 └── workspaces/
     └── <workspace_id>/
-        ├── .lock       # workspace root path + active profile
+        ├── .lock       # workspace root path, active profile, and git mode
         ├── agents/     # agent session data (persists across rebuilds)
         │   ├── claude/
         │   ├── opencode/

package/dist/commands/dev.js

@@ -8,12 +8,12 @@ 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, LABEL_MANAGED, LABEL_PROFILE, LABEL_RUNTIME_ENV, LABEL_SHADOWS, PROFILE, RUNTIME_ENV, } from "../lib/constants.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 { buildDockerfile, buildImageWithTempfile } from "../lib/dockerfile-builder.js";
 import { isImageStale } from "../lib/migrate-to-latest.js";
 import { buildShadowMountArgs, ensureShadowsInSync, expandShadowPatterns } from "../lib/shadows.js";
 import { readTotopoYaml } from "../lib/totopo-yaml.js";
-import { readActiveProfile, writeActiveProfile } from "../lib/workspace-identity.js";
+import { readActiveProfile, readGitMode, writeActiveProfile } from "../lib/workspace-identity.js";
 // --- Prompt: working directory selection -------------------------------------------------------------------------------------------------
 async function promptWorkdir(workspaceDir, cwd) {
     if (cwd === workspaceDir)
@@ -64,13 +64,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}"}}`;
+    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 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 = ""] = result.stdout.trim().split("|");
-    return { status, shadowLabel: clean(shadows), profileLabel: clean(profile), runtimeEnvLabel: clean(runtimeEnv) };
+    const [status = "", shadows = "", profile = "", runtimeEnv = "", gitMode = ""] = result.stdout.trim().split("|");
+    return {
+        status,
+        shadowLabel: clean(shadows),
+        profileLabel: clean(profile),
+        runtimeEnvLabel: clean(runtimeEnv),
+        gitModeLabel: clean(gitMode),
+    };
 }
 // --- Shadow label ------------------------------------------------------------------------------------------------------------------------
 function shadowLabel(paths) {
@@ -102,13 +108,13 @@ function runStartup(containerName, quiet) {
     return result.status === 0;
 }
 export function startContainer(opts) {
-    const { containerName, workspaceRoot, cacheDir, templatesDir, activeProfile, profileHook, expandedShadows, envFilePath, hasGit, shadowPatterns, workspaceName, noCache, quiet = false, } = opts;
+    const { containerName, workspaceRoot, cacheDir, templatesDir, activeProfile, profileHook, expandedShadows, envFilePath, hasGit, gitMode, shadowPatterns, workspaceName, noCache, quiet = false, } = opts;
     const stdio = quiet ? "pipe" : "inherit";
     // --- Sync shadows and build mount args ------------------------------------------------------------------------------------------------
     ensureShadowsInSync(cacheDir, expandedShadows, workspaceRoot);
     const shadowMountArgs = buildShadowMountArgs(cacheDir, expandedShadows);
     // --- Agent context -------------------------------------------------------------------------------------------------------------------
-    const agentDocs = buildAgentContextDocs(hasGit, shadowPatterns);
+    const agentDocs = buildAgentContextDocs(hasGit, shadowPatterns, gitMode);
     // --- Env file args -------------------------------------------------------------------------------------------------------------------
     const envFileArgs = [];
     if (envFilePath) {
@@ -128,23 +134,28 @@ export function startContainer(opts) {
         `${LABEL_PROFILE}=${activeProfile}`,
         "--label",
         `${LABEL_RUNTIME_ENV}=${runtimeEnvLabel()}`,
+        "--label",
+        `${LABEL_GIT_MODE}=${gitMode}`,
     ];
     // --- Runtime env vars -----------------------------------------------------------------------------------------------------------------
     const runtimeEnvArgs = [
         ...Object.entries(RUNTIME_ENV).flatMap(([k, v]) => ["-e", `${k}=${v}`]),
         "-e",
         `TOTOPO_WORKSPACE=${workspaceName}`,
+        "-e",
+        `TOTOPO_GIT_MODE=${gitMode}`,
     ];
     // --- Inspect container state ---------------------------------------------------------------------------------------------------------
     const info = inspectContainer(containerName);
     let containerStatus = info?.status ?? null;
-    // --- Check for shadow, profile, or runtime env mismatch ------------------------------------------------------------------------------
+    // --- Check for shadow, profile, runtime env, or git mode mismatch --------------------------------------------------------------------
     if (info !== null) {
         const expectedShadowLabel = shadowLabel(expandedShadows);
         const shadowChanged = info.shadowLabel !== expectedShadowLabel;
         const profileChanged = info.profileLabel !== activeProfile;
         const runtimeEnvChanged = info.runtimeEnvLabel !== runtimeEnvLabel();
-        if (shadowChanged || profileChanged || runtimeEnvChanged) {
+        const gitModeChanged = info.gitModeLabel !== gitMode;
+        if (shadowChanged || profileChanged || runtimeEnvChanged || gitModeChanged) {
             stopAndRemoveContainer(containerName);
             containerStatus = null;
             if (profileChanged) {
@@ -157,6 +168,10 @@ export function startContainer(opts) {
                 if (!quiet)
                     log.info("Shadow paths changed — recreating container...");
             }
+            else if (gitModeChanged) {
+                if (!quiet)
+                    log.info(`Git mode changed (${info.gitModeLabel || "<unset>"} -> ${gitMode}) — recreating container...`);
+            }
             else {
                 if (!quiet)
                     log.info("Runtime environment updated — recreating container...");
@@ -262,6 +277,8 @@ 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.strict;
     // --- Start container -----------------------------------------------------------------------------------------------------------------
     const containerOpts = {
         containerName,
@@ -273,6 +290,7 @@ export async function run(packageDir, ctx, options) {
         expandedShadows,
         envFilePath,
         hasGit,
+        gitMode,
         shadowPatterns,
         workspaceName: ctx.workspaceId,
         ...(options?.noCache !== undefined && { noCache: options.noCache }),

package/dist/commands/workspace.js

@@ -4,8 +4,10 @@
 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 { countPatternHits } from "../lib/shadows.js";
 import { buildDefaultTotopoYaml, readTotopoYaml, writeTotopoYaml } from "../lib/totopo-yaml.js";
+import { readGitMode, writeGitMode } from "../lib/workspace-identity.js";
 // --- Shadow paths menu -------------------------------------------------------------------------------------------------------------------
 async function shadowPathsMenu(ctx) {
     const yaml = readTotopoYaml(ctx.workspaceRoot);
@@ -117,6 +119,47 @@ async function removeShadowPatterns(ctx) {
     log.success(`Removed ${removeSet.size} pattern(s).`);
     await promptStopContainer(ctx);
 }
+// --- Git mode menu -----------------------------------------------------------------------------------------------------------------------
+async function gitModeMenu(ctx) {
+    const current = readGitMode(ctx.workspaceId) ?? GIT_MODE.strict;
+    note("Strict        — read-only local, no remote (recommended)\n" +
+        "Local         — local mutations allowed; remote blocked\n" +
+        "Unrestricted  — no totopo-enforced restrictions", "Git mode");
+    const choice = await select({
+        message: "Git mode:",
+        options: [
+            {
+                value: GIT_MODE.strict,
+                label: "Strict",
+                hint: current === GIT_MODE.strict ? "current · recommended" : "recommended",
+            },
+            { value: GIT_MODE.local, label: "Local", ...(current === GIT_MODE.local ? { hint: "current" } : {}) },
+            {
+                value: GIT_MODE.unrestricted,
+                label: "Unrestricted",
+                ...(current === GIT_MODE.unrestricted ? { hint: "current" } : {}),
+            },
+        ],
+        initialValue: current,
+    });
+    if (isCancel(choice))
+        return;
+    if (choice === current)
+        return;
+    if (choice === GIT_MODE.unrestricted) {
+        const confirmed = await confirm({
+            message: "Unrestricted mode disables totopo's built-in git restrictions (allows remote push/pull/fetch). Continue?",
+            initialValue: false,
+        });
+        if (isCancel(confirmed) || !confirmed) {
+            log.info("Git mode unchanged.");
+            return;
+        }
+    }
+    writeGitMode(ctx.workspaceId, choice);
+    log.success(`Git mode set to ${choice}.`);
+    await promptStopContainer(ctx);
+}
 // --- Prompt to stop container ------------------------------------------------------------------------------------------------------------
 async function promptStopContainer(ctx) {
     const containerName = ctx.containerName;
@@ -160,7 +203,9 @@ async function resetTotopoYaml(ctx) {
 // --- Manage Workspace submenu ------------------------------------------------------------------------------------------------------------
 export async function run(ctx) {
     while (true) {
+        const currentGitMode = readGitMode(ctx.workspaceId) ?? GIT_MODE.strict;
         const options = [
+            { value: "git-mode", label: "Git mode", hint: `current: ${currentGitMode}` },
             { value: "shadow-paths", label: "Shadow paths", hint: "manage shadow patterns" },
             { value: "rebuild", label: "Rebuild container", hint: "force a fresh image build" },
             { value: "clean-rebuild", label: "Clean rebuild", hint: "fresh build, no cache" },
@@ -172,6 +217,9 @@ export async function run(ctx) {
             return "back";
         }
         switch (action) {
+            case "git-mode":
+                await gitModeMenu(ctx);
+                break;
             case "shadow-paths":
                 await shadowPathsMenu(ctx);
                 break;

package/dist/lib/agent-context.js

@@ -11,7 +11,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { AGENTS_DIR, CONTAINER_HOME } from "./constants.js";
+import { AGENTS_DIR, CONTAINER_HOME, GIT_MODE } from "./constants.js";
 export const AGENT_MOUNTS = [
     {
         agent: "claude",
@@ -86,8 +86,8 @@ function renderTemplate(template, vars) {
 /**
  * Assembles the agent context markdown injected into each supported agent's config dir at session start.
  */
-export function buildAgentContextDocs(hasGit, shadowPatterns) {
-    const gitSection = loadTemplate(hasGit ? "git-available" : "git-unavailable");
+export function buildAgentContextDocs(hasGit, shadowPatterns, gitMode = GIT_MODE.strict) {
+    const gitSection = loadTemplate(hasGit ? `git-mode-${gitMode}` : "git-unavailable");
     const shadowSection = shadowPatterns && shadowPatterns.length > 0
         ? renderTemplate(loadTemplate("shadow-paths"), {
             pattern_list: shadowPatterns.map((p) => `- \`${p}\``).join("\n"),

package/dist/lib/constants.js

@@ -29,11 +29,20 @@ export const LABEL_MANAGED = "totopo.managed";
 export const LABEL_SHADOWS = "totopo.shadows";
 export const LABEL_PROFILE = "totopo.profile";
 export const LABEL_RUNTIME_ENV = "totopo.runtime-env";
+export const LABEL_GIT_MODE = "totopo.git-mode";
 // Built-in profile names (must match keys in buildDefaultTotopoYaml in totopo-yaml.ts)
 export const PROFILE = {
     default: "default",
     extended: "extended",
 };
+// Git guardrails modes (per-workspace, stored in .lock).
+// Single source of truth lives in templates/runtime-constants.mjs so container-side
+// scripts (startup.mjs, startup-git-mode.mjs) and TS code can both reference the
+// same values without drift. We re-export here so internal code keeps importing
+// from "./constants.js" as before.
+import { GIT_MODE, GIT_WRAPPER_PATH, GIT_WRAPPER_SOURCE } from "../../templates/runtime-constants.mjs";
+export { GIT_MODE, GIT_WRAPPER_PATH, GIT_WRAPPER_SOURCE };
+export const GIT_MODES = Object.values(GIT_MODE);
 // Runtime env vars injected into every container via docker run -e
 export const RUNTIME_ENV = {
     CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY: "1",

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

@@ -25,9 +25,9 @@ import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { confirm, isCancel, log } from "@clack/prompts";
+import { confirm, isCancel, log, note } from "@clack/prompts";
 import { load as loadYaml } from "js-yaml";
-import { AGENTS_DIR, CONTAINER_STARTUP, LOCK_FILE, PROFILE, SHADOWS_DIR, TOTOPO_DIR, TOTOPO_YAML, WORKSPACES_DIR } from "./constants.js";
+import { AGENTS_DIR, CONTAINER_STARTUP, GIT_MODE, GIT_WRAPPER_SOURCE, LOCK_FILE, PROFILE, 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";
@@ -390,6 +390,38 @@ function migrateRemoveLastCliUpdate() {
         }
     }
 }
+/**
+ * Pre-v3.4.0: Add the git_mode field to .lock files. Existing workspaces are kept on
+ * git_mode=local to preserve their behavior; new workspaces created via initWorkspaceDir
+ * default to git_mode=strict instead. 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 without rediscovering it on every subsequent startup. Returns the count
+ * for testing purposes; the registered Migration entry ignores it.
+ */
+export function migrateAddGitMode() {
+    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.gitMode}=`))
+                continue;
+            const trimmed = content.endsWith("\n") ? content : `${content}\n`;
+            writeFileSync(lockPath, `${trimmed}${LOCK_KEYS.gitMode}=${GIT_MODE.local}\n`);
+            migrated++;
+        }
+        catch {
+            // unreadable -- skip, will surface as a broken workspace elsewhere
+        }
+    }
+    if (migrated > 0) {
+        note(`totopo v3.4.0 introduces git modes for workspaces.\nYour existing workspace${migrated > 1 ? "s have" : " has"} been kept on 'local' (today's behavior — local commits allowed, remote blocked).\nA new 'strict' mode is available (read-only, recommended for new agent sessions).\nSwitch via the totopo menu > Manage Workspace > Git mode.`, "Git modes");
+    }
+    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
@@ -461,6 +493,7 @@ function buildMigrations(cwd, skipAnyConfirmations) {
             description: "Remove deprecated fields (schema_version, name, yaml-language-server) from totopo.yaml",
             run: () => migrateRemoveDeprecatedYamlFields(cwd),
         },
+        { from: "v3.4.0", description: "Add git_mode=local to .lock files (preserves pre-v3.4.0 behavior)", run: migrateAddGitMode },
     ];
 }
 /** Run all migrations in order. Called early in bin/totopo.js startup. */
@@ -488,5 +521,17 @@ export function isImageStale(containerName) {
     const bubblewrapCheck = spawnSync("docker", ["exec", containerName, "test", "-x", "/usr/bin/bwrap"], { stdio: "pipe" });
     if (bubblewrapCheck.status !== 0)
         return true;
+    // v3.4.0: git read-only wrapper baked in for strict git mode
+    const wrapperCheck = spawnSync("docker", ["exec", containerName, "test", "-x", GIT_WRAPPER_SOURCE], {
+        stdio: "pipe",
+    });
+    if (wrapperCheck.status !== 0)
+        return true;
+    // v3.4.0: runtime-constants module imported by startup-git-mode.mjs
+    const constantsCheck = spawnSync("docker", ["exec", containerName, "test", "-f", "/home/devuser/runtime-constants.mjs"], {
+        stdio: "pipe",
+    });
+    if (constantsCheck.status !== 0)
+        return true;
     return false;
 }

package/dist/lib/workspace-identity.js

@@ -5,12 +5,13 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { AGENTS_DIR, CONTAINER_NAME_PREFIX, LOCK_FILE, PROFILE, SHADOWS_DIR, TOTOPO_DIR, TOTOPO_YAML, WORKSPACES_DIR, } from "./constants.js";
+import { AGENTS_DIR, CONTAINER_NAME_PREFIX, GIT_MODE, GIT_MODES, LOCK_FILE, PROFILE, SHADOWS_DIR, TOTOPO_DIR, TOTOPO_YAML, WORKSPACES_DIR, } from "./constants.js";
 import { readTotopoYaml } from "./totopo-yaml.js";
 /** Maps LockFile field names to their corresponding keys written in the .lock file. */
 export const LOCK_KEYS = {
     workspaceRoot: "root",
     activeProfile: "profile",
+    gitMode: "git_mode",
 };
 /** 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]));
@@ -53,6 +54,7 @@ function parseLockFile(workspaceId) {
         return {
             workspaceRoot: partial.workspaceRoot,
             activeProfile: partial.activeProfile ?? PROFILE.default,
+            gitMode: partial.gitMode ?? GIT_MODE.strict,
         };
     }
     catch {
@@ -70,32 +72,48 @@ function writeLockFileInternal(workspaceId, data) {
 export function readLockFile(workspaceId) {
     return parseLockFile(workspaceId)?.workspaceRoot ?? null;
 }
-/** Write a workspace's lock file with the owning workspace root path. Preserves active profile. */
+/** Write a workspace's lock file with the owning workspace root path. Preserves active profile and git mode. */
 export function writeLockFile(workspaceId, workspaceRoot) {
     const existing = parseLockFile(workspaceId);
     writeLockFileInternal(workspaceId, {
         workspaceRoot,
         activeProfile: existing?.activeProfile ?? PROFILE.default,
+        gitMode: existing?.gitMode ?? GIT_MODE.strict,
     });
 }
 /** Read the active profile name. Returns null if lock file is missing. */
 export function readActiveProfile(workspaceId) {
     return parseLockFile(workspaceId)?.activeProfile ?? null;
 }
-/** Write the active profile name. Preserves workspace root path. */
+/** Write the active profile name. Preserves workspace root path and git mode. */
 export function writeActiveProfile(workspaceId, profile) {
     const existing = parseLockFile(workspaceId);
     if (!existing)
         return;
     writeLockFileInternal(workspaceId, { ...existing, activeProfile: profile });
 }
+/** Read the active git mode. Returns null if lock file is missing. Coerces unknown values to strict. */
+export function readGitMode(workspaceId) {
+    const parsed = parseLockFile(workspaceId);
+    if (!parsed)
+        return null;
+    const value = parsed.gitMode;
+    return GIT_MODES.includes(value) ? value : GIT_MODE.strict;
+}
+/** Write the active git mode. Preserves workspace root path and active profile. */
+export function writeGitMode(workspaceId, gitMode) {
+    const existing = parseLockFile(workspaceId);
+    if (!existing)
+        return;
+    writeLockFileInternal(workspaceId, { ...existing, gitMode });
+}
 // --- Workspace directory initialization --------------------------------------------------------------------------------------------------
 /** Initialize ~/.totopo/workspaces/<workspace_id>/ with lock file and subdirs. */
-export function initWorkspaceDir(workspaceId, workspaceRoot, activeProfile = PROFILE.default) {
+export function initWorkspaceDir(workspaceId, workspaceRoot, activeProfile = PROFILE.default, gitMode = GIT_MODE.strict) {
     const dir = getWorkspaceDir(workspaceId);
     mkdirSync(join(dir, AGENTS_DIR), { recursive: true });
     mkdirSync(join(dir, SHADOWS_DIR), { recursive: true });
-    writeLockFileInternal(workspaceId, { workspaceRoot, activeProfile });
+    writeLockFileInternal(workspaceId, { workspaceRoot, activeProfile, gitMode });
 }
 // --- Listing -----------------------------------------------------------------------------------------------------------------------------
 /** List all registered workspace IDs (directories with a .lock file) */

package/package.json

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

package/templates/Dockerfile

@@ -90,10 +90,20 @@ RUN groupadd --gid 1001 devuser && \
     chown -R devuser:devuser /home/devuser
 
 # ---------------------------------------------------------------------------
-# Layer 9 — Bake startup script into image
+# Layer 9 — Bake startup script + git mode helper + shared constants into image
 # ---------------------------------------------------------------------------
 COPY startup.mjs /home/devuser/startup.mjs
-RUN chown devuser:devuser /home/devuser/startup.mjs
+COPY startup-git-mode.mjs /home/devuser/startup-git-mode.mjs
+COPY runtime-constants.mjs /home/devuser/runtime-constants.mjs
+RUN chown devuser:devuser /home/devuser/startup.mjs /home/devuser/startup-git-mode.mjs /home/devuser/runtime-constants.mjs
+
+# ---------------------------------------------------------------------------
+# Layer 10 — Bake git read-only wrapper into image
+# Symlinked to /usr/local/bin/git by startup.mjs when git_mode=strict.
+# ---------------------------------------------------------------------------
+RUN mkdir -p /usr/local/share/totopo
+COPY git-readonly-wrapper.mjs /usr/local/share/totopo/git-readonly
+RUN chmod +x /usr/local/share/totopo/git-readonly
 
 WORKDIR /workspace
 

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

@@ -0,0 +1,9 @@
+## 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).
+
+totopo enforces this by:
+- Blocking remote access (push, pull, fetch, clone).
+- Leaving local git operations unrestricted.

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

@@ -0,0 +1,10 @@
+## 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.
+
+totopo enforces this by:
+- Blocking git commands that would modify the repository (attempts return a clear error).
+- Blocking remote access (push, pull, fetch, clone).
+- Allowing read-only inspection commands (e.g. `git status`, `git log`, `git show`, `git diff`, `git blame`, `git branch --list`, `git rev-parse`) — use these freely when you need to understand the repo state.

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

@@ -0,0 +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.

package/templates/context/git-unavailable.md

@@ -2,6 +2,4 @@
 
 Git is **not available** — no `.git` directory was found in the workspace root.
 
-Remote access is also **blocked container-wide** by design (`protocol.allow = never` in `/etc/gitconfig`).
-
 If git operations are needed, ask the user to run them on the host.

package/templates/git-readonly-wrapper.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+// =============================================================================
+// git-readonly-wrapper.mjs -- Read-only git wrapper for strict mode
+// Baked into the container image at /usr/local/share/totopo/git-readonly.
+// startup.mjs symlinks /usr/local/bin/git -> this file when git_mode=strict.
+// PATH puts /usr/local/bin before /usr/bin so this is invoked when an agent
+// runs `git`. Allowed subcommands forward to /usr/bin/git unchanged; blocked
+// ones print a clear error and exit non-zero.
+//
+// Threat model: guardrails for cooperative agents, not adversarial containment.
+// /usr/bin/git remains accessible by absolute path; remote ops stay blocked at
+// the gitconfig protocol layer regardless of which binary is invoked.
+//
+// The classifier is exported for unit testing. Pure Node built-ins, no deps.
+// =============================================================================
+
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const REAL_GIT = "/usr/bin/git";
+
+// -- Read-only global actions: print and exit, no subcommand needed -----------
+const READ_ONLY_GLOBAL_ACTIONS = new Set(["--version", "--help", "-h", "--html-path", "--man-path", "--info-path"]);
+
+// -- Global flags that consume the next argv element as their value -----------
+const TWO_ARG_GLOBALS = new Set(["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--super-prefix", "--attr-source"]);
+
+// -- Subcommands that are unconditionally read-only ---------------------------
+const READ_SUBCOMMANDS = new Set([
+    "status",
+    "log",
+    "show",
+    "diff",
+    "blame",
+    "reflog",
+    "rev-parse",
+    "rev-list",
+    "describe",
+    "cat-file",
+    "name-rev",
+    "fsck",
+    "shortlog",
+    "grep",
+    "count-objects",
+    "var",
+    "help",
+    "version",
+    "ls-files",
+    "ls-tree",
+    "merge-base",
+    "for-each-ref",
+    "show-ref",
+    "symbolic-ref",
+    "check-ignore",
+    "check-attr",
+    "check-mailmap",
+    "check-ref-format",
+    "whatchanged",
+    "cherry",
+    "range-diff",
+    "verify-commit",
+    "verify-tag",
+    "annotate",
+    "instaweb",
+    "diff-tree",
+    "diff-index",
+    "diff-files",
+]);
+
+// -- branch/tag flags that indicate mutation; block on any match --------------
+const BRANCH_MUTATING_FLAGS = new Set([
+    "-d",
+    "-D",
+    "-m",
+    "-M",
+    "-c",
+    "-C",
+    "--delete",
+    "--move",
+    "--copy",
+    "--set-upstream",
+    "--set-upstream-to",
+    "--unset-upstream",
+    "--edit-description",
+    "--create-reflog",
+]);
+
+const TAG_MUTATING_FLAGS = new Set([
+    "-d",
+    "-D",
+    "-m",
+    "-a",
+    "-s",
+    "-u",
+    "-f",
+    "--delete",
+    "--message",
+    "--annotate",
+    "--sign",
+    "--local-user",
+    "--cleanup",
+    "--force",
+]);
+
+// -- config flags: explicit read/write markers + flags that consume the next arg ----
+const CONFIG_READ_FLAGS = new Set([
+    "--get",
+    "--get-all",
+    "--get-regexp",
+    "--get-urlmatch",
+    "--get-color",
+    "--get-colorbool",
+    "--list",
+    "-l",
+    "--show-origin",
+    "--show-scope",
+    "--name-only",
+]);
+const CONFIG_WRITE_FLAGS = new Set([
+    "--unset",
+    "--unset-all",
+    "--add",
+    "--replace-all",
+    "--remove-section",
+    "--rename-section",
+    "-e",
+    "--edit",
+]);
+// Flags that take their next arg as a value -- skip the value when counting tokens.
+// --file/-f/--blob = scope; --type = value coercion; --default = fallback for --get.
+const CONFIG_TWO_ARG_FLAGS = new Set(["--file", "-f", "--blob", "--type", "--default"]);
+
+// -- remote: block these subactions, allow the rest (default = list) ----------
+const REMOTE_MUTATING_ACTIONS = new Set(["add", "remove", "rm", "rename", "set-url", "prune", "update", "set-head", "set-branches"]);
+
+// -- stash: only these subactions are read-only; bare `git stash` mutates -----
+const STASH_READ_ACTIONS = new Set(["list", "show"]);
+
+// -- worktree: only `list` is read-only ---------------------------------------
+const WORKTREE_READ_ACTIONS = new Set(["list"]);
+
+// -- notes: list/show are read; bare `git notes` defaults to list -------------
+const NOTES_READ_ACTIONS = new Set(["list", "show", "get-ref"]);
+
+// -- bisect: log/view are read; everything else mutates the bisect state ------
+const BISECT_READ_ACTIONS = new Set(["log", "view"]);
+
+/**
+ * Walk argv left-to-right and find the first non-flag token (the subcommand).
+ * Skips git's global option flags, including ones whose value is in the next argv slot.
+ * Returns { subcmd, rest } where rest is the args after the subcommand.
+ */
+export function findSubcommand(argv) {
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (!arg.startsWith("-")) {
+            return { subcmd: arg, rest: argv.slice(i + 1) };
+        }
+        if (TWO_ARG_GLOBALS.has(arg)) {
+            // -c key=value, -C path, --git-dir path, etc.
+            i += 2;
+            continue;
+        }
+        // --foo=bar, --bare, --no-pager, --paginate, etc. - one-arg
+        i += 1;
+    }
+    return { subcmd: null, rest: [] };
+}
+
+/**
+ * Classify a git invocation under strict mode.
+ * Returns { allow: true } or { allow: false, reason: string }.
+ * Pure function - exported for unit testing without forking.
+ */
+export function classify(argv) {
+    // Read-only global actions (--version, --help, etc.) short-circuit.
+    for (const a of argv) {
+        if (READ_ONLY_GLOBAL_ACTIONS.has(a)) return { allow: true };
+        if (a.startsWith("--list-cmds=")) return { allow: true };
+    }
+
+    const { subcmd, rest } = findSubcommand(argv);
+
+    // Bare `git` (no subcommand) prints usage - read-only.
+    if (subcmd === null) return { allow: true };
+
+    if (READ_SUBCOMMANDS.has(subcmd)) return { allow: true };
+
+    if (subcmd === "branch") {
+        for (const a of rest) {
+            if (BRANCH_MUTATING_FLAGS.has(a)) return blocked(`branch ${a}`);
+        }
+        return { allow: true };
+    }
+
+    if (subcmd === "tag") {
+        for (const a of rest) {
+            if (TAG_MUTATING_FLAGS.has(a)) return blocked(`tag ${a}`);
+        }
+        return { allow: true };
+    }
+
+    if (subcmd === "config") {
+        // Explicit write flags take precedence over everything else.
+        for (const a of rest) {
+            if (CONFIG_WRITE_FLAGS.has(a)) return blocked(`config ${a}`);
+        }
+        // Explicit read flags are an unconditional allow.
+        for (const a of rest) {
+            if (CONFIG_READ_FLAGS.has(a)) return { allow: true };
+        }
+        // Otherwise count non-flag tokens after the subcommand:
+        //   `config <key>`           -> 1 token  -> read
+        //   `config <key> <value>`   -> 2 tokens -> write
+        // Scope flags (--system, --global, ...) are flags and don't count.
+        let nonFlagCount = 0;
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (a.startsWith("-")) {
+                if (CONFIG_TWO_ARG_FLAGS.has(a)) i++; // also consume its value
+                continue;
+            }
+            nonFlagCount++;
+            if (nonFlagCount >= 2) return blocked("config (write)");
+        }
+        return { allow: true };
+    }
+
+    if (subcmd === "stash") {
+        const action = firstNonFlag(rest);
+        if (action !== null && STASH_READ_ACTIONS.has(action)) return { allow: true };
+        return blocked(action ? `stash ${action}` : "stash");
+    }
+
+    if (subcmd === "remote") {
+        const action = firstNonFlag(rest);
+        if (action !== null && REMOTE_MUTATING_ACTIONS.has(action)) return blocked(`remote ${action}`);
+        return { allow: true };
+    }
+
+    if (subcmd === "worktree") {
+        const action = firstNonFlag(rest);
+        if (action !== null && WORKTREE_READ_ACTIONS.has(action)) return { allow: true };
+        return blocked(action ? `worktree ${action}` : "worktree");
+    }
+
+    if (subcmd === "notes") {
+        const action = firstNonFlag(rest);
+        if (action === null || NOTES_READ_ACTIONS.has(action)) return { allow: true };
+        return blocked(`notes ${action}`);
+    }
+
+    if (subcmd === "bisect") {
+        const action = firstNonFlag(rest);
+        if (action !== null && BISECT_READ_ACTIONS.has(action)) return { allow: true };
+        return blocked(action ? `bisect ${action}` : "bisect");
+    }
+
+    return blocked(subcmd);
+}
+
+function firstNonFlag(args) {
+    for (const a of args) {
+        if (!a.startsWith("-")) return a;
+    }
+    return null;
+}
+
+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.`,
+    };
+}
+
+// Skip the runtime invocation when imported (e.g. by the test suite). The wrapper is normally
+// invoked through the symlink at /usr/local/bin/git, so a literal argv[1] vs import.meta.url
+// comparison wouldn't match -- realpathSync resolves the symlink before comparing.
+function detectIsMain() {
+    if (!process.argv[1]) return false;
+    try {
+        return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
+    } catch {
+        return false;
+    }
+}
+const isMain = detectIsMain();
+
+if (isMain) {
+    const result = classify(process.argv.slice(2));
+    if (!result.allow) {
+        process.stderr.write(`${result.reason}\n`);
+        process.exit(1);
+    }
+    const child = spawnSync(REAL_GIT, process.argv.slice(2), { stdio: "inherit" });
+    process.exit(child.status ?? 1);
+}

package/templates/runtime-constants.mjs

@@ -0,0 +1,18 @@
+// =============================================================================
+// runtime-constants.mjs -- Constants shared between container-side runtime
+// scripts and the totopo CLI build.
+//
+// Container-side scripts (startup.mjs, startup-git-mode.mjs) cannot import
+// from src/lib/constants.ts since the TS source isn't shipped to the image.
+// Keep this file plain ESM and import it from both sides; src/lib/constants.ts
+// re-exports the values so TS callers stay typed.
+// =============================================================================
+
+export const GIT_MODE = Object.freeze({
+    strict: "strict",
+    local: "local",
+    unrestricted: "unrestricted",
+});
+
+export const GIT_WRAPPER_PATH = "/usr/local/bin/git";
+export const GIT_WRAPPER_SOURCE = "/usr/local/share/totopo/git-readonly";

package/templates/startup-git-mode.mjs

@@ -0,0 +1,143 @@
+// =============================================================================
+// startup-git-mode.mjs -- Git mode application + verification for startup.mjs
+// Baked into the container image alongside startup.mjs at /home/devuser/.
+//
+// Strict / local / unrestricted are read from the TOTOPO_GIT_MODE env var injected by
+// dev.ts. As root we apply the requested state to /etc/gitconfig and the
+// /usr/local/bin/git symlink; as devuser we only verify that the state already
+// matches (the previous root invocation is what put it there).
+// Must use only Node.js built-ins -- no external packages available in container.
+// =============================================================================
+
+import { execSync } from "node:child_process";
+import { lstatSync, readlinkSync, symlinkSync, unlinkSync } from "node:fs";
+import { GIT_MODE, GIT_WRAPPER_PATH, GIT_WRAPPER_SOURCE } from "./runtime-constants.mjs";
+
+const VALID_GIT_MODES = Object.values(GIT_MODE);
+
+function lstatExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function isWrapperSymlinkInPlace() {
+    if (!lstatExists(GIT_WRAPPER_PATH)) return false;
+    try {
+        const st = lstatSync(GIT_WRAPPER_PATH);
+        if (!st.isSymbolicLink()) return false;
+        return readlinkSync(GIT_WRAPPER_PATH) === GIT_WRAPPER_SOURCE;
+    } catch {
+        return false;
+    }
+}
+
+function removeWrapperIfPresent() {
+    if (!lstatExists(GIT_WRAPPER_PATH)) return;
+    try {
+        unlinkSync(GIT_WRAPPER_PATH);
+    } catch {
+        // Already gone or inaccessible -- subsequent verification will catch it
+    }
+}
+
+function applyAsRoot(gitMode, protocolValue, fail) {
+    try {
+        execSync(`git config --system protocol.allow ${protocolValue}`, { stdio: "pipe" });
+    } catch {
+        fail("git mode", `failed to set protocol.allow=${protocolValue}`);
+    }
+
+    if (gitMode === GIT_MODE.strict) {
+        if (!isWrapperSymlinkInPlace()) {
+            // Remove any pre-existing /usr/local/bin/git (stale symlink, leftover binary)
+            // so symlinkSync below doesn't EEXIST.
+            removeWrapperIfPresent();
+            try {
+                symlinkSync(GIT_WRAPPER_SOURCE, GIT_WRAPPER_PATH);
+            } catch {
+                fail("git wrapper", `failed to install ${GIT_WRAPPER_PATH}`);
+            }
+        }
+        return;
+    }
+    removeWrapperIfPresent();
+}
+
+function verifyProtocol(gitMode, protocolValue, run, ok, fail) {
+    const gitProtocol = run("git config --system protocol.allow");
+    if (gitProtocol === protocolValue) {
+        ok("git mode", `${gitMode} (protocol.allow=${protocolValue})`);
+    } else {
+        fail("git mode", `expected protocol.allow=${protocolValue}, found ${gitProtocol ?? "<unset>"}`);
+    }
+}
+
+function verifyWrapper(gitMode, ok, fail, skip) {
+    if (gitMode === GIT_MODE.strict) {
+        if (isWrapperSymlinkInPlace()) {
+            ok("git read-only wrapper", `${GIT_WRAPPER_PATH} -> ${GIT_WRAPPER_SOURCE}`);
+        } else {
+            fail("git read-only wrapper", `not installed at ${GIT_WRAPPER_PATH}`);
+        }
+        return;
+    }
+    if (lstatExists(GIT_WRAPPER_PATH)) {
+        fail("git read-only wrapper", `should be absent in ${gitMode} mode`);
+    } else {
+        skip("git read-only wrapper", `not active in ${gitMode} mode`);
+    }
+}
+
+function verifyStrictWrapperRejects(ok, fail) {
+    // Probe the wrapper with a representative mutating command. The classifier
+    // rejects before forking real git, so we should see our marker on stderr.
+    let probeStderr = "";
+    let probeExit = 0;
+    try {
+        execSync(`${GIT_WRAPPER_PATH} commit -m probe`, { stdio: ["pipe", "pipe", "pipe"] });
+    } catch (err) {
+        probeStderr = (err.stderr ?? "").toString();
+        probeExit = err.status ?? 1;
+    }
+    if (probeExit !== 0 && probeStderr.includes("blocked in strict mode")) {
+        ok("strict wrapper rejects mutation", "'git commit' blocked");
+    } else {
+        fail("strict wrapper rejects mutation", "wrapper did not produce the expected error");
+    }
+}
+
+function verifyRemoteBlocked(gitMode, ok, fail, skip) {
+    if (gitMode === GIT_MODE.unrestricted) {
+        skip("remote push", "allowed in unrestricted mode (network probe skipped)");
+        return;
+    }
+    try {
+        execSync("/usr/bin/git -C /workspace push", { stdio: "pipe" });
+        fail("remote push blocked", "git push succeeded -- remote access is NOT blocked");
+    } catch {
+        ok("remote push blocked", "remote push not possible");
+    }
+}
+
+/**
+ * Apply (when root) and verify the git mode requested via TOTOPO_GIT_MODE.
+ * Reports through the caller-provided ok/fail/skip helpers so all output flows
+ * through the main startup script's section formatting and error counter.
+ */
+export function checkGitMode({ ok, fail, skip, run, isRoot }) {
+    const gitMode = VALID_GIT_MODES.includes(process.env.TOTOPO_GIT_MODE) ? process.env.TOTOPO_GIT_MODE : GIT_MODE.strict;
+    const protocolValue = gitMode === GIT_MODE.unrestricted ? "always" : "never";
+
+    if (isRoot) {
+        applyAsRoot(gitMode, protocolValue, fail);
+    }
+
+    verifyProtocol(gitMode, protocolValue, run, ok, fail);
+    verifyWrapper(gitMode, ok, fail, skip);
+    if (gitMode === GIT_MODE.strict) verifyStrictWrapperRejects(ok, fail);
+    verifyRemoteBlocked(gitMode, ok, fail, skip);
+}

package/templates/startup.mjs

@@ -8,6 +8,7 @@
 
 import { execSync } from "node:child_process";
 import { readFileSync, writeFileSync } from "node:fs";
+import { checkGitMode } from "./startup-git-mode.mjs";
 
 const run = (cmd) => {
     try {
@@ -84,19 +85,8 @@ if (idOutput?.includes("uid=1001")) {
     fail("non-root user", "devuser not found or wrong uid -- container is misconfigured");
 }
 
-const gitProtocol = run("git config --system protocol.allow");
-if (gitProtocol === "never") {
-    ok("git remote block", "protocol.allow = never");
-} else {
-    fail("git remote block", "not set -- rebuild the container");
-}
-
-try {
-    execSync("/usr/bin/git -C /workspace push", { stdio: "pipe" });
-    fail("push blocked", "git push succeeded -- remote access is NOT blocked");
-} catch {
-    ok("push blocked", "remote push not possible");
-}
+// -- Git mode (strict / local / unrestricted) - applied + verified by separate module --
+checkGitMode({ ok, fail, skip, run, isRoot });
 
 // -- AI tools -----------------------------------------------------------------
 section("AI tools");

package/templates/context/git-available.md

@@ -1,5 +0,0 @@
-## Git availability
-
-Git is fully available for local operations (commit, branch, log, diff, status, etc.).
-
-Remote access (push, pull, fetch, clone) is **blocked at the system level** by design — `protocol.allow = never` is enforced in `/etc/gitconfig` and cannot be overridden without root. This is a deliberate security boundary: the container has no access to remote repositories. Ask the user to run any remote git operations from the host.