@imdeadpool/guardex 7.0.41 → 7.0.43

package/src/cockpit/welcome.js

@@ -0,0 +1,266 @@
+'use strict';
+
+const path = require('node:path');
+const { WELCOME_SHORTCUTS } = require('./shortcuts');
+const { colorize, getCockpitTheme } = require('./theme');
+
+const DEFAULT_WIDTH = 76;
+const MIN_WIDTH = 48;
+const MAX_WIDTH = 88;
+
+const DEFAULT_AGENTS = ['codex', 'claude', 'opencode', 'cursor', 'gemini'];
+const GITGUARDEX_BRAND = [
+  '  ____  _   _   _   ___   ___   _____  __',
+  ' / ___|| | | | / \\ |  _ \\ |  _ \\ | ____|\\ \\/ /',
+  '| |  _ | | | |/ _ \\| |_) || | | ||  _|   \\  /',
+  '| |_| || |_| / ___ \\  _ < | |_| || |___  /  \\',
+  ' \\____| \\___/_/   \\_\\_| \\_\\____/ |_____|/_/\\_\\',
+];
+const GITGUARDEX_STRAPLINE = 'guarded multi-agent cockpit';
+
+function stringValue(value, fallback = '') {
+  if (typeof value === 'string') {
+    return value.trim() || fallback;
+  }
+  if (value === null || value === undefined) {
+    return fallback;
+  }
+  return String(value).trim() || fallback;
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    const text = stringValue(value);
+    if (text) {
+      return text;
+    }
+  }
+  return '';
+}
+
+function boundedWidth(settings = {}) {
+  const width = Number(settings.width || settings.welcomeWidth || settings.cockpitWidth);
+  if (!Number.isFinite(width)) {
+    return DEFAULT_WIDTH;
+  }
+  return Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, Math.floor(width)));
+}
+
+function truncate(value, width) {
+  const text = stringValue(value);
+  if (width <= 0) {
+    return '';
+  }
+  if (text.length <= width) {
+    return text;
+  }
+  if (width <= 3) {
+    return text.slice(0, width);
+  }
+  return `${text.slice(0, width - 3)}...`;
+}
+
+function repoName(state = {}, settings = {}) {
+  const explicit = firstString(
+    settings.repoName,
+    state.repoName,
+    state.projectName,
+    state.repo,
+    state.name,
+  );
+  if (explicit) {
+    return explicit;
+  }
+
+  const repoPath = firstString(state.repoPath, state.repoRoot, state.agentsStatus && state.agentsStatus.repoRoot);
+  if (!repoPath) {
+    return '-';
+  }
+  return path.basename(repoPath) || repoPath;
+}
+
+function currentBranch(state = {}) {
+  return firstString(
+    state.currentBranch,
+    state.branch,
+    state.git && state.git.currentBranch,
+    state.agentsStatus && state.agentsStatus.currentBranch,
+  ) || '-';
+}
+
+function baseBranch(state = {}, settings = {}) {
+  return firstString(
+    state.baseBranch,
+    state.base,
+    settings.baseBranch,
+    settings.defaultBase,
+    state.git && state.git.baseBranch,
+    state.agentsStatus && state.agentsStatus.baseBranch,
+  ) || '-';
+}
+
+function hooksStatus(state = {}) {
+  const hooks = state.hooks || state.gitHooks || state.safetyHooks;
+  const direct = firstString(
+    state.hooksStatus,
+    state.hookStatus,
+    state.coreHooksPath,
+    state.safety && state.safety.hooksStatus,
+  );
+  if (direct) {
+    return direct;
+  }
+  if (typeof hooks === 'boolean') {
+    return hooks ? 'enabled' : 'disabled';
+  }
+  if (typeof hooks === 'string') {
+    return hooks.trim();
+  }
+  if (hooks && typeof hooks === 'object') {
+    return firstString(hooks.status, hooks.state, hooks.coreHooksPath, hooks.path, hooks.value);
+  }
+  return '';
+}
+
+function safetyStatus(state = {}) {
+  return firstString(
+    state.safetyStatus,
+    state.guardStatus,
+    state.guardexStatus,
+    state.safety && state.safety.status,
+    state.agentsStatus && state.agentsStatus.safetyStatus,
+  ) || 'unknown';
+}
+
+function normalizeAgentList(value) {
+  if (typeof value === 'string') {
+    return value.split(',').map((item) => item.trim()).filter(Boolean);
+  }
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((agent) => {
+      if (typeof agent === 'string') {
+        return agent.trim();
+      }
+      if (agent && typeof agent === 'object') {
+        return firstString(agent.name, agent.agent, agent.id, agent.label);
+      }
+      return '';
+    })
+    .filter(Boolean);
+}
+
+function availableAgents(state = {}, settings = {}) {
+  const agents = [
+    ...normalizeAgentList(settings.availableAgents),
+    ...normalizeAgentList(settings.agents),
+    ...normalizeAgentList(state.availableAgents),
+    ...normalizeAgentList(state.agents),
+  ];
+
+  const source = agents.length > 0 ? agents : DEFAULT_AGENTS;
+  return Array.from(new Set(source)).join(', ');
+}
+
+function totalLockCount(state = {}) {
+  if (Number.isFinite(state.lockCount)) {
+    return Math.max(0, Math.floor(state.lockCount));
+  }
+  if (Array.isArray(state.locks)) {
+    return state.locks.length;
+  }
+  if (state.lockSummary && Number.isFinite(state.lockSummary.count)) {
+    return Math.max(0, Math.floor(state.lockSummary.count));
+  }
+  if (state.agentsStatus && Number.isFinite(state.agentsStatus.lockCount)) {
+    return Math.max(0, Math.floor(state.agentsStatus.lockCount));
+  }
+
+  const sessions = Array.isArray(state.sessions) ? state.sessions : [];
+  return sessions.reduce((count, session) => {
+    if (Array.isArray(session.locks)) {
+      return count + session.locks.length;
+    }
+    if (Number.isFinite(session.lockCount)) {
+      return count + Math.max(0, Math.floor(session.lockCount));
+    }
+    return count;
+  }, 0);
+}
+
+function row(label, value) {
+  return `${label.padEnd(12)} ${value}`;
+}
+
+function boxedLine(value, width) {
+  const innerWidth = width - 4;
+  const text = truncate(value, innerWidth);
+  return `| ${text.padEnd(innerWidth)} |`;
+}
+
+function divider(width) {
+  return `+${'-'.repeat(width - 2)}+`;
+}
+
+function emptyLine(width) {
+  return boxedLine('', width);
+}
+
+function themedBoxedLine(value, width, token, theme) {
+  return colorize(boxedLine(value, width), token, theme);
+}
+
+function renderWelcomePage(state = {}, settings = {}) {
+  const width = boundedWidth(settings);
+  const theme = getCockpitTheme(settings.theme || state.theme, settings);
+  const hooks = hooksStatus(state);
+  const lines = [
+    colorize(divider(width), 'border', theme),
+    themedBoxedLine('gitguardex | gx cockpit', width, 'title', theme),
+    themedBoxedLine('Guardian cockpit ready. No active agent lanes.', width, 'secondary', theme),
+    emptyLine(width),
+  ];
+
+  GITGUARDEX_BRAND.forEach((brandLine) => {
+    lines.push(themedBoxedLine(brandLine, width, 'accent', theme));
+  });
+  lines.push(
+    emptyLine(width),
+    themedBoxedLine(GITGUARDEX_STRAPLINE, width, 'heading', theme),
+  );
+
+  lines.push(
+    emptyLine(width),
+    themedBoxedLine(row('Repo:', repoName(state, settings)), width, 'secondary', theme),
+    themedBoxedLine(row('Branch:', `${currentBranch(state)} (base ${baseBranch(state, settings)})`), width, 'secondary', theme),
+    themedBoxedLine(row('Safety:', safetyStatus(state)), width, 'success', theme),
+  );
+
+  if (hooks) {
+    lines.push(themedBoxedLine(row('Hooks:', hooks), width, 'secondary', theme));
+  }
+
+  lines.push(
+    themedBoxedLine(row('Locks:', String(totalLockCount(state))), width, 'accent', theme),
+    themedBoxedLine(row('Agents:', availableAgents(state, settings)), width, 'secondary', theme),
+    emptyLine(width),
+    themedBoxedLine('Shortcuts', width, 'heading', theme),
+    ...WELCOME_SHORTCUTS.map(([key, label]) => themedBoxedLine(`  ${key} ${label}`, width, 'secondary', theme)),
+    emptyLine(width),
+    themedBoxedLine('Next actions', width, 'heading', theme),
+    themedBoxedLine('  n new agent  - start a guarded agent lane', width, 'secondary', theme),
+    themedBoxedLine('  t terminal   - open a repo terminal', width, 'secondary', theme),
+    themedBoxedLine('  l logs       - tail apps/logs/*.log and lane events', width, 'secondary', theme),
+    themedBoxedLine('  p projects   - switch repo (no lane selected)', width, 'secondary', theme),
+    themedBoxedLine('  s settings   - tune cockpit defaults', width, 'secondary', theme),
+    colorize(divider(width), 'border', theme),
+  );
+
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = {
+  renderWelcomePage,
+};

package/src/context.js

@@ -21,7 +21,14 @@ const GLOBAL_INSTALL_COMMAND = `npm i -g ${packageJson.name}`;
 const OPENSPEC_PACKAGE = '@fission-ai/openspec';
 const OMC_PACKAGE = 'oh-my-claude-sisyphus';
 const OMC_REPO_URL = 'https://github.com/Yeachan-Heo/oh-my-claudecode';
-const COLONY_PACKAGE = '@imdeadpool/colony-cli';
+// Colony was published under @imdeadpool/colony-cli historically; the new
+// canonical npm name is `colonyq`. The companion-install prompt that
+// gx status / gx setup show now reads `npm i -g colonyq`. Post-install
+// setup the user runs themselves (gitguardex only owns the `npm i -g` step):
+//   colony install --ide codex
+//   npx skills add recodeee/colony/skills/colony-mcp
+//   colony health
+const COLONY_PACKAGE = 'colonyq';
 const NPX_BIN = process.env.GUARDEX_NPX_BIN || 'npx';
 const GUARDEX_HOME_DIR = path.resolve(process.env.GUARDEX_HOME_DIR || os.homedir());
 const GLOBAL_TOOLCHAIN_SERVICES = [
@@ -61,14 +68,34 @@ const OPTIONAL_LOCAL_COMPANION_TOOLS = [
     installArgs: ['skills', 'add', 'JuliusBrussee/caveman'],
   },
 ];
-const GH_BIN = process.env.GUARDEX_GH_BIN || 'gh';
+function commandAvailable(command) {
+  const result = cp.spawnSync(command, ['--version'], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+function resolveGithubCliBin(env = process.env) {
+  const explicit = String(env.GUARDEX_GH_BIN || '').trim();
+  if (explicit) {
+    return explicit;
+  }
+  return commandAvailable('ghx') ? 'ghx' : 'gh';
+}
+
+const GH_BIN = resolveGithubCliBin();
+const RTK_BIN = process.env.GUARDEX_RTK_BIN || 'rtk';
 const REQUIRED_SYSTEM_TOOLS = [
   {
     name: 'gh',
-    displayName: 'GitHub (gh)',
+    displayName: GH_BIN === 'ghx' ? 'GitHub (ghx proxy)' : 'GitHub (gh)',
     command: GH_BIN,
     installHint: 'https://cli.github.com/',
   },
+  {
+    name: 'rtk',
+    displayName: 'RTK (rtk)',
+    command: RTK_BIN,
+    installHint: 'Install RTK and ensure `rtk` is on PATH.',
+  },
 ];
 const MAINTAINER_RELEASE_REPO = path.resolve(
   process.env.GUARDEX_RELEASE_REPO || PACKAGE_ROOT,
@@ -117,44 +144,40 @@ function toDestinationPath(relativeTemplatePath) {
   throw new Error(`Unsupported template path: ${relativeTemplatePath}`);
 }
 
+// scripts/ ↔ templates/scripts/ layout convention (single source of truth):
+//
+// 1. PAIRED files (10): tracked on both sides; scripts/<file> is a symlink
+//    to ../templates/scripts/<file> per PR #548. See
+//    scripts/check-script-symlinks.sh for the exact list. CI + the
+//    .githooks/pre-commit shim both enforce that no symlink is ever
+//    replaced with a regular file. Edit only the templates/scripts/ copy;
+//    the symlink propagates.
+//
+// 2. SCAFFOLD-ONLY files (the 4 below + workflows + vscode extension):
+//    tracked only under templates/; scaffolded into gitignored
+//    scripts/<file> (or .githooks/<file>, etc.) by `gx setup`. Consumer
+//    repos receive a regular file copy at the destination; gitguardex
+//    itself receives the same copy and ignores it via the
+//    multiagent-safety .gitignore block. Edit only the templates/ copy.
+//
+// If a file you're about to add fits pattern (1), also add it to
+// scripts/check-script-symlinks.sh's required_symlinks list. If it fits
+// pattern (2), append the destination path to .gitignore's multiagent-
+// safety block (auto-managed by syncManagedGitignoreLines below).
 const TEMPLATE_FILES = [
   'scripts/agent-session-state.js',
+  'scripts/agent-preflight.sh',
   'scripts/guardex-docker-loader.sh',
   'scripts/guardex-env.sh',
-  'scripts/install-vscode-active-agents-extension.js',
   'github/pull.yml.example',
+  'github/workflows/ci.yml',
+  'github/workflows/ci-full.yml',
   'github/workflows/cr.yml',
-  'vscode/guardex-active-agents/package.json',
-  'vscode/guardex-active-agents/extension.js',
-  'vscode/guardex-active-agents/session-schema.js',
-  'vscode/guardex-active-agents/README.md',
-  'vscode/guardex-active-agents/icon.png',
-  'vscode/guardex-active-agents/fileicons/gitguardex-fileicons.json',
-  'vscode/guardex-active-agents/fileicons/icons/agent.svg',
-  'vscode/guardex-active-agents/fileicons/icons/branch.svg',
-  'vscode/guardex-active-agents/fileicons/icons/config.svg',
-  'vscode/guardex-active-agents/fileicons/icons/hook.svg',
-  'vscode/guardex-active-agents/fileicons/icons/openspec.svg',
-  'vscode/guardex-active-agents/fileicons/icons/plan.svg',
-  'vscode/guardex-active-agents/fileicons/icons/spec.svg',
+  'github/workflows/README.md',
 ];
 
 const PACKAGE_ROOT_SOURCE_OVERRIDES = new Set([
   'scripts/agent-session-state.js',
-  'scripts/install-vscode-active-agents-extension.js',
-  'vscode/guardex-active-agents/package.json',
-  'vscode/guardex-active-agents/extension.js',
-  'vscode/guardex-active-agents/session-schema.js',
-  'vscode/guardex-active-agents/README.md',
-  'vscode/guardex-active-agents/icon.png',
-  'vscode/guardex-active-agents/fileicons/gitguardex-fileicons.json',
-  'vscode/guardex-active-agents/fileicons/icons/agent.svg',
-  'vscode/guardex-active-agents/fileicons/icons/branch.svg',
-  'vscode/guardex-active-agents/fileicons/icons/config.svg',
-  'vscode/guardex-active-agents/fileicons/icons/hook.svg',
-  'vscode/guardex-active-agents/fileicons/icons/openspec.svg',
-  'vscode/guardex-active-agents/fileicons/icons/plan.svg',
-  'vscode/guardex-active-agents/fileicons/icons/spec.svg',
 ]);
 
 const LEGACY_WORKFLOW_SHIM_SPECS = [
@@ -180,7 +203,6 @@ const LEGACY_MANAGED_REPO_FILES = [
   ...LEGACY_WORKFLOW_SHIMS,
   'scripts/agent-session-state.js',
   'scripts/guardex-docker-loader.sh',
-  'scripts/install-vscode-active-agents-extension.js',
   'scripts/guardex-env.sh',
   'scripts/install-agent-git-hooks.sh',
   '.githooks/pre-commit',
@@ -289,13 +311,13 @@ const MANAGED_REPO_SCAN_IGNORED_FOLDERS = [
 const MANAGED_GITIGNORE_PATHS = [
   '.omx/',
   '.omc/',
+  '.codex/',
   '!.vscode/',
   '.vscode/*',
   '!.vscode/settings.json',
   'scripts/agent-session-state.js',
   'scripts/guardex-docker-loader.sh',
   'scripts/guardex-env.sh',
-  'scripts/install-vscode-active-agents-extension.js',
   '.githooks',
   'oh-my-codex/',
   LOCK_FILE_RELATIVE,
@@ -345,6 +367,7 @@ const SUGGESTIBLE_COMMANDS = [
   'hook',
   'migrate',
   'install-agent-skills',
+  'cockpit',
   'agents',
   'merge',
   'finish',
@@ -364,6 +387,8 @@ const SUGGESTIBLE_COMMANDS = [
   'copy-commands',
   'print-agents-snippet',
   'release',
+  'budget',
+  'ci-init',
 ];
 // CLI_COMMAND_GROUPS is the grouped source of truth the `gx --help` /
 // `gx` no-args renderer uses. Each group is ordered roughly by how often a
@@ -409,6 +434,8 @@ const CLI_COMMAND_GROUPS = [
     description: 'Review / cleanup bots, AI setup prompts, and safety reports.',
     commands: [
       ['agents', 'Start/stop repo-scoped review + cleanup bots'],
+      ['pr-review', 'Run local Codex/Claude PR review and post inline GitHub comments or write an artifact'],
+      ['cockpit', 'Create or attach to a repo tmux cockpit session'],
       ['install-agent-skills', 'Install Guardex Codex/Claude skills into the user home'],
       ['prompt', 'Print AI setup checklist or named slices (--exec, --part, --list-parts, --snippet)'],
       ['report', 'Security/safety reports (e.g. OpenSSF scorecard, session severity)'],
@@ -449,6 +476,9 @@ const DOCTOR_AUTO_FINISH_MESSAGE_MAX = 160;
 const AI_SETUP_PART_ALIASES = new Map([
   ['task', 'task-loop'],
   ['loop', 'task-loop'],
+  ['compact-commands', 'rtk'],
+  ['command-compression', 'rtk'],
+  ['token-commands', 'rtk'],
   ['reviewbot', 'review-bot'],
   ['forksync', 'fork-sync'],
 ]);
@@ -500,6 +530,18 @@ const AI_SETUP_PARTS = [
       'gx locks claim --branch "<agent-branch>" <file...>',
     ],
   },
+  {
+    name: 'rtk',
+    label: 'RTK command compression',
+    promptLines: [
+      'Prefer RTK wrappers for noisy shell discovery and verification when `rtk` is available; fall back to raw commands when missing.',
+      'Files: `rtk ls .`, `rtk read <file>`, `rtk read <file> -l aggressive`, `rtk smart <file>`, `rtk find "<glob>" .`, `rtk grep "<pattern>" .`, `rtk diff <a> <b>`.',
+      'Git/GitHub: `rtk git status`, `rtk git diff`, `rtk git log -n 10`, `rtk gh pr list`, `rtk gh pr view <id>`.',
+      'Tests/build: `rtk test <cmd>`, `rtk err <cmd>`, `rtk jest`, `rtk vitest`, `rtk playwright test`, `rtk pytest`, `rtk cargo test`, `rtk tsc`, `rtk lint`.',
+      'Use `rtk gain`, `rtk discover`, and `rtk session` to audit savings; use `rtk proxy <command>` only when raw passthrough is required.',
+      'Do not wrap machine-readable commands with RTK when code parses stdout (`--porcelain`, `--json`, NUL-delimited output, or exact stdout contracts).',
+    ],
+  },
   {
     name: 'integrate',
     label: 'Integrate',
@@ -680,6 +722,7 @@ module.exports = {
   GLOBAL_TOOLCHAIN_SERVICES,
   GLOBAL_TOOLCHAIN_PACKAGES,
   OPTIONAL_LOCAL_COMPANION_TOOLS,
+  resolveGithubCliBin,
   GH_BIN,
   REQUIRED_SYSTEM_TOOLS,
   MAINTAINER_RELEASE_REPO,

package/src/doctor/index.js

@@ -3,6 +3,7 @@ const {
   path,
   TOOL_NAME,
   SHORT_TOOL_NAME,
+  GH_BIN,
   LOCK_FILE_RELATIVE,
   REQUIRED_MANAGED_REPO_FILES,
   OMX_SCAFFOLD_DIRECTORIES,
@@ -442,7 +443,7 @@ function finishDoctorSandboxBranch(blocked, metadata, options = {}) {
     };
   }
 
-  const ghBin = process.env.GUARDEX_GH_BIN || 'gh';
+  const ghBin = GH_BIN;
   if (!isCommandAvailable(ghBin)) {
     return {
       status: 'skipped',
@@ -890,7 +891,7 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
 
   const originAvailable = hasOriginRemote(repoRoot);
   const explicitGhBin = Boolean(String(process.env.GUARDEX_GH_BIN || '').trim());
-  const ghBin = process.env.GUARDEX_GH_BIN || 'gh';
+  const ghBin = GH_BIN;
   const ghAvailable =
     originAvailable &&
     (explicitGhBin || originRemoteLooksLikeGithub(repoRoot)) &&

package/src/finish/index.js

@@ -26,6 +26,7 @@ const {
   parseFinishArgs,
   parseSyncArgs,
 } = require('../cli/args');
+const submoduleModule = require('../submodule');
 
 function claimLocksForAutoCommit(repoRoot, worktreePath, branch) {
   const changedFiles = uniquePreserveOrder([
@@ -134,6 +135,7 @@ function autoCommitWorktreeForFinish(repoRoot, worktreePath, branch, options) {
 }
 
 function cleanup(rawArgs) {
+  const activeCwd = process.cwd();
   const options = parseCleanupArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
 
@@ -168,7 +170,11 @@ function cleanup(rawArgs) {
   }
 
   const runCleanupCycle = () => {
-    const runResult = runPackageAsset('worktreePrune', args, { cwd: repoRoot, stdio: 'inherit' });
+    const runResult = runPackageAsset('worktreePrune', args, {
+      cwd: repoRoot,
+      stdio: 'inherit',
+      env: { GUARDEX_PRUNE_ACTIVE_CWD: activeCwd },
+    });
     if (runResult.status !== 0) {
       throw new Error('Cleanup command failed');
     }
@@ -234,6 +240,7 @@ function merge(rawArgs) {
 }
 
 function finish(rawArgs, defaults = {}) {
+  const activeCwd = process.cwd();
   const options = parseFinishArgs(rawArgs, defaults);
   const repoRoot = resolveRepoRoot(options.target);
 
@@ -299,6 +306,32 @@ function finish(rawArgs, defaults = {}) {
         console.log(`[${TOOL_NAME}] [dry-run] Would auto-commit pending changes on '${branch}'.`);
       }
 
+      if (options.advanceSubmodules && worktreePath) {
+        const gitmodulesPath = path.join(worktreePath, '.gitmodules');
+        if (fs.existsSync(gitmodulesPath)) {
+          if (options.dryRun) {
+            const preview = submoduleModule.advance({
+              target: worktreePath,
+              push: false,
+              commit: false,
+              dryRun: true,
+            });
+            console.log(`[${TOOL_NAME}] [dry-run] Would advance submodules for '${branch}':`);
+            submoduleModule.printAdvanceResult(preview);
+          } else {
+            const advanceResult = submoduleModule.advance({
+              target: worktreePath,
+              push: false,
+              commit: true,
+              dryRun: false,
+            });
+            submoduleModule.printAdvanceResult(advanceResult);
+          }
+        } else {
+          console.log(`[${TOOL_NAME}] --advance-submodules ignored: '${branch}' has no .gitmodules.`);
+        }
+      }
+
       const finishArgs = [
         '--branch',
         branch,
@@ -325,7 +358,11 @@ function finish(rawArgs, defaults = {}) {
         continue;
       }
 
-      const finishResult = runPackageAsset('branchFinish', finishArgs, { cwd: repoRoot, stdio: 'pipe' });
+      const finishResult = runPackageAsset('branchFinish', finishArgs, {
+        cwd: repoRoot,
+        stdio: 'pipe',
+        env: { GUARDEX_FINISH_ACTIVE_CWD: activeCwd },
+      });
       if (finishResult.stdout) {
         process.stdout.write(finishResult.stdout);
       }

package/src/git/index.js

@@ -319,6 +319,70 @@ function writeProtectedBranches(repoRoot, branches) {
   gitRun(repoRoot, ['config', GIT_PROTECTED_BRANCHES_KEY, branches.join(' ')]);
 }
 
+const SUBMODULE_AUTO_SYNC_CONFIGS = [
+  {
+    key: 'pull.recurseSubmodules',
+    value: 'true',
+    note: 'auto-update submodule working dirs on `git pull`',
+  },
+  {
+    key: 'fetch.recurseSubmodules',
+    value: 'on-demand',
+    note: 'fetch submodule commits as parent pointers move',
+  },
+];
+
+function ensureSubmoduleAutoSync(repoRoot, dryRun) {
+  const gitmodulesPath = path.join(repoRoot, '.gitmodules');
+  if (!fs.existsSync(gitmodulesPath)) {
+    return [];
+  }
+
+  const operations = [];
+  for (const { key, value, note } of SUBMODULE_AUTO_SYNC_CONFIGS) {
+    const existing = readGitConfig(repoRoot, key);
+    if (existing) {
+      operations.push({
+        status: 'unchanged',
+        file: `git config ${key}`,
+        note: `respected pre-existing value: ${existing}`,
+      });
+      continue;
+    }
+    if (!dryRun) {
+      gitRun(repoRoot, ['config', key, value]);
+    }
+    operations.push({
+      status: dryRun ? 'would-set' : 'set',
+      file: `git config ${key}`,
+      note: `${value} (${note})`,
+    });
+  }
+
+  if (dryRun) {
+    operations.push({
+      status: 'would-sync',
+      file: 'git submodule update --init --recursive',
+      note: 'snap submodule working dirs to parent index',
+    });
+    return operations;
+  }
+
+  const result = gitRun(
+    repoRoot,
+    ['submodule', 'update', '--init', '--recursive'],
+    { allowFailure: true },
+  );
+  operations.push({
+    status: result.status === 0 ? 'synced' : 'failed',
+    file: 'git submodule update --init --recursive',
+    note: result.status === 0
+      ? 'submodule working dirs snapped to parent index'
+      : `failed: ${(result.stderr || '').trim().split('\n')[0] || 'unknown'}`,
+  });
+  return operations;
+}
+
 function readGitConfig(repoRoot, key) {
   const result = gitRun(repoRoot, ['config', '--get', key], { allowFailure: true });
   if (result.status !== 0) {
@@ -697,6 +761,7 @@ module.exports = {
   hasSignificantWorkingTreeChanges,
   readProtectedBranches,
   ensureSetupProtectedBranches,
+  ensureSubmoduleAutoSync,
   writeProtectedBranches,
   readGitConfig,
   resolveBaseBranch,