@imdeadpool/guardex 7.0.15 → 7.0.18

package/bin/multiagent-safety.js

@@ -5,12 +5,20 @@ const os = require('node:os');
 const path = require('node:path');
 const cp = require('node:child_process');
 
-const packageJsonPath = path.resolve(__dirname, '..', 'package.json');
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const packageJsonPath = path.join(PACKAGE_ROOT, 'package.json');
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
 
 const TOOL_NAME = 'gitguardex';
 const SHORT_TOOL_NAME = 'gx';
+if (!process.env.GUARDEX_CLI_ENTRY) {
+  process.env.GUARDEX_CLI_ENTRY = __filename;
+}
+if (!process.env.GUARDEX_NODE_BIN) {
+  process.env.GUARDEX_NODE_BIN = process.execPath;
+}
 const LEGACY_NAMES = ['guardex', 'multiagent-safety'];
+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';
@@ -84,48 +92,71 @@ const COMPOSE_HINT_FILES = [
   'compose.yaml',
 ];
 
-const TEMPLATE_ROOT = path.resolve(__dirname, '..', 'templates');
+const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, 'templates');
+
+const HOOK_NAMES = ['pre-commit', 'pre-push', 'post-merge', 'post-checkout'];
 
 const TEMPLATE_FILES = [
-  'scripts/agent-branch-start.sh',
-  'scripts/agent-branch-finish.sh',
-  'scripts/codex-agent.sh',
+  'scripts/agent-session-state.js',
   'scripts/guardex-docker-loader.sh',
-  'scripts/review-bot-watch.sh',
-  'scripts/agent-worktree-prune.sh',
-  'scripts/agent-file-locks.py',
   'scripts/guardex-env.sh',
-  'scripts/install-agent-git-hooks.sh',
-  'scripts/openspec/init-plan-workspace.sh',
-  'scripts/openspec/init-change-workspace.sh',
-  'githooks/pre-commit',
-  'githooks/pre-push',
-  'githooks/post-merge',
-  'githooks/post-checkout',
-  'codex/skills/gitguardex/SKILL.md',
-  'codex/skills/guardex-merge-skills-to-dev/SKILL.md',
-  'claude/commands/gitguardex.md',
+  'scripts/install-vscode-active-agents-extension.js',
   'github/pull.yml.example',
   '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',
 ];
 
-const REQUIRED_WORKFLOW_FILES = [
+const SCRIPT_SHIMS = [
+  { relativePath: 'scripts/agent-branch-start.sh', kind: 'shell', command: ['branch', 'start'] },
+  { relativePath: 'scripts/agent-branch-finish.sh', kind: 'shell', command: ['branch', 'finish'] },
+  { relativePath: 'scripts/agent-branch-merge.sh', kind: 'shell', command: ['branch', 'merge'] },
+  { relativePath: 'scripts/codex-agent.sh', kind: 'shell', command: ['internal', 'run-shell', 'codexAgent'] },
+  { relativePath: 'scripts/review-bot-watch.sh', kind: 'shell', command: ['internal', 'run-shell', 'reviewBot'] },
+  { relativePath: 'scripts/agent-worktree-prune.sh', kind: 'shell', command: ['worktree', 'prune'] },
+  { relativePath: 'scripts/agent-file-locks.py', kind: 'python', command: ['locks'] },
+  { relativePath: 'scripts/openspec/init-plan-workspace.sh', kind: 'shell', command: ['internal', 'run-shell', 'planInit'] },
+  { relativePath: 'scripts/openspec/init-change-workspace.sh', kind: 'shell', command: ['internal', 'run-shell', 'changeInit'] },
+];
+
+const LEGACY_MANAGED_REPO_FILES = [
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-branch-merge.sh',
+  'scripts/agent-session-state.js',
+  'scripts/codex-agent.sh',
   'scripts/guardex-docker-loader.sh',
+  'scripts/install-vscode-active-agents-extension.js',
+  'scripts/review-bot-watch.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/agent-file-locks.py',
   'scripts/guardex-env.sh',
   'scripts/install-agent-git-hooks.sh',
+  'scripts/openspec/init-plan-workspace.sh',
+  'scripts/openspec/init-change-workspace.sh',
   '.githooks/pre-commit',
+  '.githooks/pre-push',
   '.githooks/post-merge',
+  '.githooks/post-checkout',
+  '.codex/skills/gitguardex/SKILL.md',
+  '.codex/skills/guardex-merge-skills-to-dev/SKILL.md',
+  '.claude/commands/gitguardex.md',
+];
+
+const REQUIRED_WORKFLOW_FILES = [
+  ...TEMPLATE_FILES.map((entry) => toDestinationPath(entry)),
+  ...SCRIPT_SHIMS.map((entry) => entry.relativePath),
+  ...HOOK_NAMES.map((entry) => path.posix.join('.githooks', entry)),
   '.omx/state/agent-file-locks.json',
 ];
 
-const REQUIRED_PACKAGE_SCRIPTS = {
+const LEGACY_MANAGED_PACKAGE_SCRIPTS = {
   'agent:codex': 'bash ./scripts/codex-agent.sh',
   'agent:branch:start': 'bash ./scripts/agent-branch-start.sh',
   'agent:branch:finish': 'bash ./scripts/agent-branch-finish.sh',
+  'agent:branch:merge': 'bash ./scripts/agent-branch-merge.sh',
   'agent:cleanup': 'gx cleanup',
   'agent:hooks:install': 'bash ./scripts/install-agent-git-hooks.sh',
   'agent:locks:claim': 'python3 ./scripts/agent-file-locks.py claim',
@@ -146,31 +177,47 @@ const REQUIRED_PACKAGE_SCRIPTS = {
   'agent:finish': 'gx finish --all',
 };
 
+const PACKAGE_SCRIPT_ASSETS = {
+  branchStart: path.join(TEMPLATE_ROOT, 'scripts', 'agent-branch-start.sh'),
+  branchFinish: path.join(TEMPLATE_ROOT, 'scripts', 'agent-branch-finish.sh'),
+  branchMerge: path.join(TEMPLATE_ROOT, 'scripts', 'agent-branch-merge.sh'),
+  codexAgent: path.join(TEMPLATE_ROOT, 'scripts', 'codex-agent.sh'),
+  reviewBot: path.join(TEMPLATE_ROOT, 'scripts', 'review-bot-watch.sh'),
+  worktreePrune: path.join(TEMPLATE_ROOT, 'scripts', 'agent-worktree-prune.sh'),
+  lockTool: path.join(TEMPLATE_ROOT, 'scripts', 'agent-file-locks.py'),
+  planInit: path.join(TEMPLATE_ROOT, 'scripts', 'openspec', 'init-plan-workspace.sh'),
+  changeInit: path.join(TEMPLATE_ROOT, 'scripts', 'openspec', 'init-change-workspace.sh'),
+};
+
+const USER_LEVEL_SKILL_ASSETS = [
+  {
+    source: path.join(TEMPLATE_ROOT, 'codex', 'skills', 'gitguardex', 'SKILL.md'),
+    destination: path.join('.codex', 'skills', 'gitguardex', 'SKILL.md'),
+  },
+  {
+    source: path.join(TEMPLATE_ROOT, 'codex', 'skills', 'guardex-merge-skills-to-dev', 'SKILL.md'),
+    destination: path.join('.codex', 'skills', 'guardex-merge-skills-to-dev', 'SKILL.md'),
+  },
+  {
+    source: path.join(TEMPLATE_ROOT, 'claude', 'commands', 'gitguardex.md'),
+    destination: path.join('.claude', 'commands', 'gitguardex.md'),
+  },
+];
+
 const EXECUTABLE_RELATIVE_PATHS = new Set([
-  'scripts/agent-branch-start.sh',
-  'scripts/agent-branch-finish.sh',
-  'scripts/codex-agent.sh',
+  'scripts/agent-session-state.js',
   'scripts/guardex-docker-loader.sh',
-  'scripts/review-bot-watch.sh',
-  'scripts/agent-worktree-prune.sh',
-  'scripts/agent-file-locks.py',
-  'scripts/install-agent-git-hooks.sh',
-  'scripts/openspec/init-plan-workspace.sh',
-  'scripts/openspec/init-change-workspace.sh',
-  '.githooks/pre-commit',
-  '.githooks/pre-push',
-  '.githooks/post-merge',
-  '.githooks/post-checkout',
+  'scripts/install-vscode-active-agents-extension.js',
+  ...SCRIPT_SHIMS.map((entry) => entry.relativePath),
+  ...HOOK_NAMES.map((entry) => path.posix.join('.githooks', entry)),
 ]);
 
 const CRITICAL_GUARDRAIL_PATHS = new Set([
   'AGENTS.md',
-  '.githooks/pre-commit',
-  '.githooks/pre-push',
-  '.githooks/post-merge',
-  '.githooks/post-checkout',
+  ...HOOK_NAMES.map((entry) => path.posix.join('.githooks', entry)),
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
+  'scripts/agent-branch-merge.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/codex-agent.sh',
   'scripts/agent-file-locks.py',
@@ -197,9 +244,6 @@ const MANAGED_GITIGNORE_PATHS = [
   'scripts/agent-file-locks.py',
   '.githooks',
   'oh-my-codex/',
-  '.codex/skills/gitguardex/SKILL.md',
-  '.codex/skills/guardex-merge-skills-to-dev/SKILL.md',
-  '.claude/commands/gitguardex.md',
   LOCK_FILE_RELATIVE,
 ];
 const REPO_SCAFFOLD_DIRECTORIES = ['bin'];
@@ -232,7 +276,14 @@ const SUGGESTIBLE_COMMANDS = [
   'status',
   'setup',
   'doctor',
+  'branch',
+  'locks',
+  'worktree',
+  'hook',
+  'migrate',
+  'install-agent-skills',
   'agents',
+  'merge',
   'finish',
   'report',
   'protect',
@@ -256,7 +307,14 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['status', 'Show GitGuardex CLI + service health without modifying files'],
   ['setup', 'Install, repair, and verify guardrails (flags: --repair, --install-only, --target)'],
   ['doctor', 'Repair drift + verify (auto-sandboxes on protected main)'],
+  ['branch', 'CLI-owned branch workflow surface (start/finish/merge)'],
+  ['locks', 'CLI-owned file lock surface (claim/allow-delete/release/status/validate)'],
+  ['worktree', 'CLI-owned worktree cleanup surface (prune)'],
+  ['hook', 'Hook dispatch/install surface used by managed shims'],
+  ['migrate', 'Convert legacy repo-local installs to the new shim-based CLI-owned surface'],
+  ['install-agent-skills', 'Install Guardex Codex/Claude skills into the user home'],
   ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
+  ['merge', 'Create/reuse an integration lane and merge overlapping agent branches'],
   ['sync', 'Sync agent branches with origin/<base>'],
   ['finish', 'Commit + PR + merge completed agent branches (--all, --branch)'],
   ['cleanup', 'Prune merged/stale agent branches and worktrees'],
@@ -265,7 +323,7 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['prompt', 'Print AI setup checklist (--exec, --snippet)'],
   ['report', 'Security/safety reports (e.g. OpenSSF scorecard)'],
   ['help', 'Show this help output'],
-  ['version', 'Print GuardeX version'],
+  ['version', 'Print GitGuardex version'],
 ];
 const DEPRECATED_COMMAND_ALIASES = new Map([
   ['init', { target: 'setup', hint: 'gx setup' }],
@@ -280,6 +338,9 @@ const DEPRECATED_COMMAND_ALIASES = new Map([
 const AGENT_BOT_DESCRIPTIONS = [
   ['agents', 'Start/stop review + cleanup bots for this repo'],
 ];
+const DOCTOR_AUTO_FINISH_DETAIL_LIMIT = 6;
+const DOCTOR_AUTO_FINISH_BRANCH_LABEL_MAX = 72;
+const DOCTOR_AUTO_FINISH_MESSAGE_MAX = 160;
 
 function envFlagIsTruthy(raw) {
   const lowered = String(raw || '').trim().toLowerCase();
@@ -296,26 +357,28 @@ function defaultAgentWorktreeRelativeDir(env = process.env) {
 
 const AI_SETUP_PROMPT = `GitGuardex (gx) setup checklist for Codex/Claude in this repo.
 
-1) Install:    npm i -g @imdeadpool/guardex && gh --version
+1) Install:    ${GLOBAL_INSTALL_COMMAND} && gh --version
 2) Bootstrap:  gx setup
 3) Repair:     gx doctor
-4) Task loop:  bash scripts/codex-agent.sh "<task>" "<agent>"
-               or branch-start -> python3 scripts/agent-file-locks.py claim -> branch-finish
-5) Finish:     gx finish --all
-6) Cleanup:    gx cleanup
-7) OpenSpec:   /opsx:propose -> /opsx:apply -> /opsx:archive
-8) Optional:   gx protect add release staging
-9) Optional:   gx sync --check && gx sync
-10) Review bot: install https://github.com/apps/cr-gpt + set OPENAI_API_KEY
-11) Fork sync:  install https://github.com/apps/pull + cp .github/pull.yml.example .github/pull.yml
+4) Task loop:  gx branch start "<task>" "<agent>"
+               then gx locks claim --branch "<agent-branch>" <file...> -> gx branch finish
+5) Integrate:  gx merge --branch <agent-a> --branch <agent-b>
+6) Finish:     gx finish --all
+7) Cleanup:    gx cleanup
+8) OpenSpec:   /opsx:propose -> /opsx:apply -> /opsx:archive
+9) Optional:   gx protect add release staging
+10) Optional:  gx sync --check && gx sync
+11) Review bot: install https://github.com/apps/cr-gpt + set OPENAI_API_KEY
+12) Fork sync:  install https://github.com/apps/pull + cp .github/pull.yml.example .github/pull.yml
 `;
 
-const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
+const AI_SETUP_COMMANDS = `${GLOBAL_INSTALL_COMMAND}
 gh --version
 gx setup
 gx doctor
-bash scripts/codex-agent.sh "<task>" "<agent>"
-python3 scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>
+gx branch start "<task>" "<agent>"
+gx locks claim --branch "<agent-branch>" <file...>
+gx merge --branch "<agent-a>" --branch "<agent-b>"
 gx finish --all
 gx cleanup
 gx protect add release staging
@@ -345,7 +408,17 @@ function runtimeVersion() {
 }
 
 function supportsAnsiColors() {
-  return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
+  const forced = String(process.env.FORCE_COLOR || '').trim().toLowerCase();
+  if (['0', 'false', 'no', 'off'].includes(forced)) {
+    return false;
+  }
+  if (forced.length > 0) {
+    return true;
+  }
+  if (process.env.NO_COLOR) {
+    return false;
+  }
+  return Boolean(process.stdout.isTTY) && process.env.TERM !== 'dumb';
 }
 
 function colorize(text, colorCode) {
@@ -355,6 +428,56 @@ function colorize(text, colorCode) {
   return `\u001B[${colorCode}m${text}\u001B[0m`;
 }
 
+function doctorOutputColorCode(status) {
+  const normalized = String(status || '').trim().toLowerCase();
+  if (['active', 'done', 'ok', 'safe', 'success'].includes(normalized)) {
+    return '32';
+  }
+  if (normalized === 'disabled') {
+    return '36';
+  }
+  if (['degraded', 'pending', 'skip', 'warn', 'warning'].includes(normalized)) {
+    return '33';
+  }
+  if (['error', 'fail', 'inactive', 'unsafe'].includes(normalized)) {
+    return '31';
+  }
+  return null;
+}
+
+function colorizeDoctorOutput(text, status) {
+  const colorCode = doctorOutputColorCode(status);
+  return colorCode ? colorize(text, colorCode) : text;
+}
+
+function detectAutoFinishDetailStatus(detail) {
+  const trimmed = String(detail || '').trim();
+  const match = trimmed.match(/^\[(\w+)\]/);
+  if (match) {
+    return match[1].toLowerCase();
+  }
+  if (/^Skipped\b/i.test(trimmed) || /^No local agent branches found\b/i.test(trimmed)) {
+    return 'skip';
+  }
+  return null;
+}
+
+function detectAutoFinishSummaryStatus(summary) {
+  if (!summary || summary.enabled === false) {
+    return detectAutoFinishDetailStatus(summary?.details?.[0]);
+  }
+  if ((summary.failed || 0) > 0) {
+    return 'fail';
+  }
+  if ((summary.completed || 0) > 0) {
+    return 'done';
+  }
+  if ((summary.skipped || 0) > 0) {
+    return 'skip';
+  }
+  return null;
+}
+
 function statusDot(status) {
   if (status === 'active') {
     return colorize('●', '32'); // green
@@ -500,10 +623,188 @@ function run(cmd, args, options = {}) {
     encoding: 'utf8',
     stdio: options.stdio || 'pipe',
     cwd: options.cwd,
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+    timeout: options.timeout,
+  });
+}
+
+function extractTargetedArgs(rawArgs, defaultTarget = process.cwd()) {
+  const passthrough = [];
+  let target = defaultTarget;
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === '--target' || arg === '-t') {
+      target = requireValue(rawArgs, index, '--target');
+      index += 1;
+      continue;
+    }
+    passthrough.push(arg);
+  }
+
+  return { target, passthrough };
+}
+
+function packageAssetEnv(extraEnv = {}) {
+  return {
+    GUARDEX_CLI_ENTRY: __filename,
+    GUARDEX_NODE_BIN: process.execPath,
+    ...extraEnv,
+  };
+}
+
+function packageAssetPath(assetKey) {
+  const assetPath = PACKAGE_SCRIPT_ASSETS[assetKey];
+  if (!assetPath) {
+    throw new Error(`Unknown package asset: ${assetKey}`);
+  }
+  if (!fs.existsSync(assetPath)) {
+    throw new Error(`Missing package asset: ${assetPath}`);
+  }
+  return assetPath;
+}
+
+function runPackageAsset(assetKey, rawArgs, options = {}) {
+  const assetPath = packageAssetPath(assetKey);
+  let cmd = 'bash';
+  if (assetPath.endsWith('.py')) {
+    cmd = 'python3';
+  } else if (assetPath.endsWith('.js')) {
+    cmd = process.execPath;
+  }
+  return run(cmd, [assetPath, ...rawArgs], {
+    cwd: options.cwd || process.cwd(),
+    stdio: options.stdio || 'pipe',
     timeout: options.timeout,
+    env: packageAssetEnv(options.env),
   });
 }
 
+function invokePackageAsset(assetKey, rawArgs, options = {}) {
+  const result = runPackageAsset(assetKey, rawArgs, options);
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.status !== 0) {
+    throw new Error(`${assetKey} command failed with status ${result.status}`);
+  }
+  process.exitCode = 0;
+  return result;
+}
+
+function formatElapsedDuration(ms) {
+  const durationMs = Number.isFinite(ms) ? Math.max(0, ms) : 0;
+  if (durationMs < 1000) {
+    return `${Math.round(durationMs)}ms`;
+  }
+  if (durationMs < 10_000) {
+    return `${(durationMs / 1000).toFixed(1)}s`;
+  }
+  return `${Math.round(durationMs / 1000)}s`;
+}
+
+function truncateMiddle(value, maxLength) {
+  const text = String(value || '');
+  const limit = Number.isFinite(maxLength) ? Math.max(4, maxLength) : 0;
+  if (!limit || text.length <= limit) {
+    return text;
+  }
+
+  const visible = limit - 1;
+  const headLength = Math.ceil(visible / 2);
+  const tailLength = Math.floor(visible / 2);
+  return `${text.slice(0, headLength)}…${text.slice(text.length - tailLength)}`;
+}
+
+function truncateTail(value, maxLength) {
+  const text = String(value || '');
+  const limit = Number.isFinite(maxLength) ? Math.max(4, maxLength) : 0;
+  if (!limit || text.length <= limit) {
+    return text;
+  }
+  return `${text.slice(0, limit - 1)}…`;
+}
+
+function compactAutoFinishPathSegments(message) {
+  return String(message || '').replace(/\((\/[^)]+)\)/g, (_, rawPath) => {
+    if (
+      rawPath.includes(`${path.sep}.omx${path.sep}agent-worktrees${path.sep}`) ||
+      rawPath.includes(`${path.sep}.omc${path.sep}agent-worktrees${path.sep}`)
+    ) {
+      return `(${path.basename(rawPath)})`;
+    }
+    return `(${truncateMiddle(rawPath, 72)})`;
+  });
+}
+
+function summarizeAutoFinishDetail(detail) {
+  const trimmed = String(detail || '').trim();
+  const match = trimmed.match(/^\[(\w+)\]\s+([^:]+):\s*(.*)$/);
+  if (!match) {
+    return truncateTail(compactAutoFinishPathSegments(trimmed), DOCTOR_AUTO_FINISH_MESSAGE_MAX);
+  }
+
+  const [, status, rawBranch, rawMessage] = match;
+  const branch = truncateMiddle(rawBranch, DOCTOR_AUTO_FINISH_BRANCH_LABEL_MAX);
+  let message = String(rawMessage || '').trim();
+
+  if (status === 'fail') {
+    message = message.replace(/^auto-finish failed\.?\s*/i, '');
+    if (/\[agent-sync-guard\]/.test(message) && /Resolve conflicts/i.test(message)) {
+      message = 'rebase conflict in finish flow; run rebase --continue or rebase --abort in the source-probe worktree';
+    } else if (/unable to compute ahead\/behind/i.test(message)) {
+      const aheadBehindMatch = message.match(/unable to compute ahead\/behind(?: \([^)]+\))?/i);
+      if (aheadBehindMatch) {
+        message = aheadBehindMatch[0];
+      }
+    } else if (/remote ref does not exist/i.test(message)) {
+      message = 'branch merged, but the remote ref was already removed during cleanup';
+    }
+  }
+
+  message = compactAutoFinishPathSegments(message)
+    .replace(/\s+\|\s+/g, '; ')
+    .trim();
+
+  return `[${status}] ${branch}: ${truncateTail(message, DOCTOR_AUTO_FINISH_MESSAGE_MAX)}`;
+}
+
+function printAutoFinishSummary(summary, options = {}) {
+  const enabled = Boolean(summary && summary.enabled);
+  const details = Array.isArray(summary && summary.details) ? summary.details : [];
+  const baseBranch = String(options.baseBranch || summary?.baseBranch || '').trim();
+  const verbose = Boolean(options.verbose);
+  const detailLimit = Number.isFinite(options.detailLimit)
+    ? Math.max(0, options.detailLimit)
+    : DOCTOR_AUTO_FINISH_DETAIL_LIMIT;
+
+  if (enabled) {
+    console.log(
+      colorizeDoctorOutput(
+        `[${TOOL_NAME}] Auto-finish sweep (base=${baseBranch}): attempted=${summary.attempted}, completed=${summary.completed}, skipped=${summary.skipped}, failed=${summary.failed}`,
+        detectAutoFinishSummaryStatus(summary),
+      ),
+    );
+    const visibleDetails = verbose ? details : details.slice(0, detailLimit).map(summarizeAutoFinishDetail);
+    for (const detail of visibleDetails) {
+      console.log(colorizeDoctorOutput(`[${TOOL_NAME}]   ${detail}`, detectAutoFinishDetailStatus(detail)));
+    }
+    if (!verbose && details.length > detailLimit) {
+      console.log(
+        colorizeDoctorOutput(
+          `[${TOOL_NAME}]   … ${details.length - detailLimit} more branch result(s). Re-run with --verbose-auto-finish for full details.`,
+          'warn',
+        ),
+      );
+    }
+    return;
+  }
+
+  if (details.length > 0) {
+    const detail = verbose ? details[0] : summarizeAutoFinishDetail(details[0]);
+    console.log(colorizeDoctorOutput(`[${TOOL_NAME}] ${detail}`, detectAutoFinishDetailStatus(detail)));
+  }
+}
+
 function gitRun(repoRoot, args, { allowFailure = false } = {}) {
   const result = run('git', ['-C', repoRoot, ...args]);
   if (!allowFailure && result.status !== 0) {
@@ -628,6 +929,9 @@ function toDestinationPath(relativeTemplatePath) {
   if (relativeTemplatePath.startsWith('github/')) {
     return `.${relativeTemplatePath}`;
   }
+  if (relativeTemplatePath.startsWith('vscode/')) {
+    return relativeTemplatePath;
+  }
   throw new Error(`Unsupported template path: ${relativeTemplatePath}`);
 }
 
@@ -665,6 +969,111 @@ function isCriticalGuardrailPath(relativePath) {
   return CRITICAL_GUARDRAIL_PATHS.has(relativePath);
 }
 
+function shellSingleQuote(value) {
+  return `'${String(value).replace(/'/g, `'\"'\"'`)}'`;
+}
+
+function renderShellDispatchShim(commandParts) {
+  const rendered = commandParts.map((part) => shellSingleQuote(part)).join(' ');
+  return (
+    '#!/usr/bin/env bash\n' +
+    'set -euo pipefail\n' +
+    '\n' +
+    'if [[ -n "${GUARDEX_CLI_ENTRY:-}" ]]; then\n' +
+    '  node_bin="${GUARDEX_NODE_BIN:-node}"\n' +
+    `  exec "$node_bin" "$GUARDEX_CLI_ENTRY" ${rendered} "$@"\n` +
+    'fi\n' +
+    '\n' +
+    'resolve_guardex_cli() {\n' +
+    '  if [[ -n "${GUARDEX_CLI_BIN:-}" ]]; then\n' +
+    '    printf \'%s\' "$GUARDEX_CLI_BIN"\n' +
+    '    return 0\n' +
+    '  fi\n' +
+    '  if command -v gx >/dev/null 2>&1; then\n' +
+    '    printf \'%s\' "gx"\n' +
+    '    return 0\n' +
+    '  fi\n' +
+    '  if command -v gitguardex >/dev/null 2>&1; then\n' +
+    '    printf \'%s\' "gitguardex"\n' +
+    '    return 0\n' +
+    '  fi\n' +
+    '  echo "[gitguardex-shim] Missing gx CLI in PATH." >&2\n' +
+    '  exit 1\n' +
+    '}\n' +
+    '\n' +
+    'cli_bin="$(resolve_guardex_cli)"\n' +
+    `exec "$cli_bin" ${rendered} "$@"\n`
+  );
+}
+
+function renderPythonDispatchShim(commandParts) {
+  return (
+    '#!/usr/bin/env python3\n' +
+    'import os\n' +
+    'import shutil\n' +
+    'import subprocess\n' +
+    'import sys\n' +
+    '\n' +
+    `COMMAND = ${JSON.stringify(commandParts)}\n` +
+    '\n' +
+    'entry = os.environ.get("GUARDEX_CLI_ENTRY")\n' +
+    'if entry:\n' +
+    '    node_bin = os.environ.get("GUARDEX_NODE_BIN") or shutil.which("node") or "node"\n' +
+    '    raise SystemExit(subprocess.call([node_bin, entry, *COMMAND, *sys.argv[1:]]))\n' +
+    'cli = os.environ.get("GUARDEX_CLI_BIN") or shutil.which("gx") or shutil.which("gitguardex")\n' +
+    'if not cli:\n' +
+    '    sys.stderr.write("[gitguardex-shim] Missing gx CLI in PATH.\\n")\n' +
+    '    raise SystemExit(1)\n' +
+    'raise SystemExit(subprocess.call([cli, *COMMAND, *sys.argv[1:]]))\n'
+  );
+}
+
+function renderManagedFile(repoRoot, relativePath, content, options = {}) {
+  const destinationPath = path.join(repoRoot, relativePath);
+  const destinationExists = fs.existsSync(destinationPath);
+  const force = Boolean(options.force);
+  const dryRun = Boolean(options.dryRun);
+
+  if (destinationExists) {
+    const existingContent = fs.readFileSync(destinationPath, 'utf8');
+    if (existingContent === content) {
+      ensureExecutable(destinationPath, relativePath, dryRun);
+      return { status: 'unchanged', file: relativePath };
+    }
+    if (!force && !isCriticalGuardrailPath(relativePath)) {
+      throw new Error(`Refusing to overwrite existing file without --force: ${relativePath}`);
+    }
+  }
+
+  ensureParentDir(repoRoot, destinationPath, dryRun);
+  if (!dryRun) {
+    fs.writeFileSync(destinationPath, content, 'utf8');
+    ensureExecutable(destinationPath, relativePath, dryRun);
+  }
+
+  if (destinationExists && !force && isCriticalGuardrailPath(relativePath)) {
+    return { status: dryRun ? 'would-repair-critical' : 'repaired-critical', file: relativePath };
+  }
+
+  return { status: destinationExists ? 'overwritten' : 'created', file: relativePath };
+}
+
+function ensureGeneratedScriptShim(repoRoot, spec, options = {}) {
+  const content = spec.kind === 'python'
+    ? renderPythonDispatchShim(spec.command)
+    : renderShellDispatchShim(spec.command);
+  return renderManagedFile(repoRoot, spec.relativePath, content, options);
+}
+
+function ensureHookShim(repoRoot, hookName, options = {}) {
+  return renderManagedFile(
+    repoRoot,
+    path.posix.join('.githooks', hookName),
+    renderShellDispatchShim(['hook', 'run', hookName]),
+    options,
+  );
+}
+
 function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
   const sourcePath = path.join(TEMPLATE_ROOT, relativeTemplatePath);
   const destinationRelativePath = toDestinationPath(relativeTemplatePath);
@@ -842,8 +1251,7 @@ function writeLockState(repoRoot, payload, dryRun) {
   fs.writeFileSync(lockPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
 }
 
-function ensurePackageScripts(repoRoot, dryRun, options = {}) {
-  const force = Boolean(options.force);
+function removeLegacyPackageScripts(repoRoot, dryRun) {
   const packagePath = path.join(repoRoot, 'package.json');
   if (!fs.existsSync(packagePath)) {
     return { status: 'skipped', file: 'package.json', note: 'package.json not found' };
@@ -859,29 +1267,87 @@ function ensurePackageScripts(repoRoot, dryRun, options = {}) {
   const existingScripts = pkg.scripts && typeof pkg.scripts === 'object'
     ? pkg.scripts
     : {};
-  const hasExistingAgentScripts = Object.keys(existingScripts).some((key) => key.startsWith('agent:'));
-  if (hasExistingAgentScripts && !force) {
-    return { status: 'unchanged', file: 'package.json', note: 'preserved existing agent:* scripts' };
-  }
-
   pkg.scripts = existingScripts;
   let changed = false;
-  for (const [key, value] of Object.entries(REQUIRED_PACKAGE_SCRIPTS)) {
-    if (pkg.scripts[key] !== value) {
-      pkg.scripts[key] = value;
+  for (const [key, value] of Object.entries(LEGACY_MANAGED_PACKAGE_SCRIPTS)) {
+    if (existingScripts[key] === value) {
+      delete existingScripts[key];
       changed = true;
     }
   }
 
   if (!changed) {
-    return { status: 'unchanged', file: 'package.json' };
+    return { status: 'unchanged', file: 'package.json', note: 'no Guardex-managed agent:* scripts found' };
   }
 
   if (!dryRun) {
     fs.writeFileSync(packagePath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
   }
 
-  return { status: 'updated', file: 'package.json' };
+  return { status: dryRun ? 'would-update' : 'updated', file: 'package.json', note: 'removed Guardex-managed agent:* scripts' };
+}
+
+function installUserLevelAsset(asset, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const force = Boolean(options.force);
+  const destinationPath = path.join(GUARDEX_HOME_DIR, asset.destination);
+  const sourceContent = fs.readFileSync(asset.source, 'utf8');
+  const destinationExists = fs.existsSync(destinationPath);
+
+  if (destinationExists) {
+    const existingContent = fs.readFileSync(destinationPath, 'utf8');
+    if (existingContent === sourceContent) {
+      return { status: 'unchanged', file: asset.destination };
+    }
+    if (!force) {
+      return { status: 'skipped-conflict', file: asset.destination };
+    }
+  }
+
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+    fs.writeFileSync(destinationPath, sourceContent, 'utf8');
+  }
+  return { status: destinationExists ? (dryRun ? 'would-update' : 'updated') : 'created', file: asset.destination };
+}
+
+function removeLegacyManagedRepoFile(repoRoot, relativePath, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const force = Boolean(options.force);
+  const absolutePath = path.join(repoRoot, relativePath);
+  if (!fs.existsSync(absolutePath)) {
+    return { status: 'unchanged', file: relativePath, note: 'not present' };
+  }
+  if (!fs.statSync(absolutePath).isFile()) {
+    return { status: 'skipped-conflict', file: relativePath, note: 'not a regular file' };
+  }
+
+  const skillAsset = USER_LEVEL_SKILL_ASSETS.find((asset) => asset.destination === relativePath);
+  if (skillAsset) {
+    const userLevelPath = path.join(GUARDEX_HOME_DIR, skillAsset.destination);
+    if (!fs.existsSync(userLevelPath)) {
+      return { status: 'skipped', file: relativePath, note: 'user-level replacement not installed' };
+    }
+  }
+
+  const templateRelative = skillAsset
+    ? skillAsset.source.slice(TEMPLATE_ROOT.length + 1)
+    : relativePath.replace(/^\./, '');
+  const sourcePath = path.join(TEMPLATE_ROOT, templateRelative);
+  if (!fs.existsSync(sourcePath)) {
+    return { status: 'skipped', file: relativePath, note: 'template source missing' };
+  }
+
+  const sourceContent = fs.readFileSync(sourcePath, 'utf8');
+  const existingContent = fs.readFileSync(absolutePath, 'utf8');
+  if (existingContent !== sourceContent && !force) {
+    return { status: 'skipped-conflict', file: relativePath, note: 'local edits differ from managed template' };
+  }
+
+  if (!dryRun) {
+    fs.rmSync(absolutePath, { force: true });
+  }
+  return { status: dryRun ? 'would-remove' : 'removed', file: relativePath };
 }
 
 function ensureAgentsSnippet(repoRoot, dryRun, options = {}) {
@@ -1121,7 +1587,7 @@ function parseSetupArgs(rawArgs, defaults) {
 }
 
 function parseDoctorArgs(rawArgs) {
-  return parseRepoTraversalArgs(rawArgs, {
+  const doctorDefaults = {
     target: process.cwd(),
     dropStaleLocks: true,
     skipAgents: false,
@@ -1131,7 +1597,24 @@ function parseDoctorArgs(rawArgs) {
     json: false,
     allowProtectedBaseWrite: false,
     waitForMerge: true,
-  });
+    verboseAutoFinish: false,
+  };
+  const forwardedArgs = [];
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === '--verbose-auto-finish') {
+      doctorDefaults.verboseAutoFinish = true;
+      continue;
+    }
+    if (arg === '--compact-auto-finish') {
+      doctorDefaults.verboseAutoFinish = false;
+      continue;
+    }
+    forwardedArgs.push(arg);
+  }
+
+  return parseRepoTraversalArgs(forwardedArgs, doctorDefaults);
 }
 
 function normalizeWorkspacePath(relativePath) {
@@ -1230,7 +1713,7 @@ function assertProtectedMainWriteAllowed(options, commandName) {
   throw new Error(
     `${commandName} blocked on protected branch '${blocked.branch}' in an initialized repo.\n` +
     `Keep local '${blocked.branch}' pull-only: start an agent branch/worktree first:\n` +
-    `  bash scripts/agent-branch-start.sh "<task>" "codex"\n` +
+    `  gx branch start "<task>" "codex"\n` +
     `Override once only when intentional: --allow-protected-base-write`,
   );
 }
@@ -1309,6 +1792,7 @@ function buildSandboxDoctorArgs(options, sandboxTarget) {
   if (options.skipGitignore) args.push('--no-gitignore');
   if (!options.dropStaleLocks) args.push('--keep-stale-locks');
   args.push(options.waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge');
+  if (options.verboseAutoFinish) args.push('--verbose-auto-finish');
   if (options.json) args.push('--json');
   return args;
 }
@@ -1455,8 +1939,7 @@ function startProtectedBaseSandbox(blocked, { taskName, sandboxSuffix }) {
     return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
 
-  const startResult = run('bash', [
-    startScript,
+  const startResult = runPackageAsset('branchStart', [
     '--task',
     taskName,
     '--agent',
@@ -1605,8 +2088,7 @@ function collectWorktreeDirtyPaths(worktreePath) {
 }
 
 function collectDoctorForceAddPaths(worktreePath) {
-  return TEMPLATE_FILES
-    .map((entry) => toDestinationPath(entry))
+  return REQUIRED_WORKFLOW_FILES
     .filter((relativePath) => relativePath.startsWith('scripts/') || relativePath.startsWith('.githooks/'))
     .filter((relativePath) => fs.existsSync(path.join(worktreePath, relativePath)));
 }
@@ -1658,13 +2140,13 @@ function claimDoctorChangedLocks(metadata) {
   ]));
   const deletedPaths = collectDoctorDeletedPaths(metadata.worktreePath);
   if (changedPaths.length > 0) {
-    run('python3', [lockScript, 'claim', '--branch', metadata.branch, ...changedPaths], {
+    runPackageAsset('lockTool', ['claim', '--branch', metadata.branch, ...changedPaths], {
       cwd: metadata.worktreePath,
       timeout: 30_000,
     });
   }
   if (deletedPaths.length > 0) {
-    run('python3', [lockScript, 'allow-delete', '--branch', metadata.branch, ...deletedPaths], {
+    runPackageAsset('lockTool', ['allow-delete', '--branch', metadata.branch, ...deletedPaths], {
       cwd: metadata.worktreePath,
       timeout: 30_000,
     });
@@ -1810,7 +2292,7 @@ function finishDoctorSandboxBranch(blocked, metadata, options = {}) {
 
   const finishResult = run(
     'bash',
-    [finishScript, '--branch', metadata.branch, '--base', blocked.branch, '--via-pr', waitForMergeArg],
+    [finishScript, '--branch', metadata.branch, '--base', blocked.branch, '--via-pr', waitForMergeArg, '--cleanup'],
     { cwd: metadata.worktreePath, timeout: finishTimeoutMs },
   );
   if (isSpawnFailure(finishResult)) {
@@ -1881,7 +2363,7 @@ function mergeDoctorSandboxRepairsBackToProtectedBase(options, blocked, metadata
     ...(autoCommitResult.stagedFiles || []),
     ...OMX_SCAFFOLD_DIRECTORIES,
     ...Array.from(OMX_SCAFFOLD_FILES.keys()),
-    ...TEMPLATE_FILES.map((entry) => toDestinationPath(entry)),
+    ...REQUIRED_WORKFLOW_FILES,
     'bin',
     'package.json',
     '.gitignore',
@@ -2019,9 +2501,7 @@ function mergeDoctorSandboxRepairsBackToProtectedBase(options, blocked, metadata
 }
 
 function syncDoctorLocalSupportFiles(repoRoot, dryRun) {
-  return TEMPLATE_FILES
-    .filter((entry) => entry.startsWith('codex/') || entry.startsWith('claude/'))
-    .map((entry) => ensureTemplateFilePresent(repoRoot, entry, dryRun));
+  return [];
 }
 
 function runDoctorInSandbox(options, blocked) {
@@ -2207,6 +2687,7 @@ function runDoctorInSandbox(options, blocked) {
     postSandboxAutoFinishSummary = autoFinishReadyAgentBranches(blocked.repoRoot, {
       baseBranch: blocked.branch,
       dryRun: options.dryRun,
+      waitForMerge: options.waitForMerge,
       excludeBranches: [metadata.branch],
     });
   }
@@ -2300,23 +2781,17 @@ function runDoctorInSandbox(options, blocked) {
         if (finishResult.stderr) process.stderr.write(finishResult.stderr);
       } else if (finishResult.status === 'failed') {
         console.log(`[${TOOL_NAME}] Auto-finish flow failed for sandbox branch '${metadata.branch}'.`);
-        console.log(`[guardex] Auto-finish flow failed for sandbox branch '${metadata.branch}'.`);
+        console.log(`[${TOOL_NAME}] Auto-finish flow failed for sandbox branch '${metadata.branch}'.`);
         if (finishResult.stdout) process.stdout.write(finishResult.stdout);
         if (finishResult.stderr) process.stderr.write(finishResult.stderr);
       } else {
         console.log(`[${TOOL_NAME}] Auto-finish skipped: ${finishResult.note}.`);
       }
 
-      if (postSandboxAutoFinishSummary.enabled) {
-        console.log(
-          `[${TOOL_NAME}] Auto-finish sweep (base=${blocked.branch}): attempted=${postSandboxAutoFinishSummary.attempted}, completed=${postSandboxAutoFinishSummary.completed}, skipped=${postSandboxAutoFinishSummary.skipped}, failed=${postSandboxAutoFinishSummary.failed}`,
-        );
-        for (const detail of postSandboxAutoFinishSummary.details) {
-          console.log(`[${TOOL_NAME}]   ${detail}`);
-        }
-      } else if (postSandboxAutoFinishSummary.details.length > 0) {
-        console.log(`[${TOOL_NAME}] ${postSandboxAutoFinishSummary.details[0]}`);
-      }
+      printAutoFinishSummary(postSandboxAutoFinishSummary, {
+        baseBranch: blocked.branch,
+        verbose: options.verboseAutoFinish,
+      });
       if (omxScaffoldSyncResult.status === 'synced') {
         console.log(`[${TOOL_NAME}] Synced .omx scaffold back to protected branch workspace.`);
       } else if (omxScaffoldSyncResult.status === 'unchanged') {
@@ -2871,6 +3346,7 @@ function hasSignificantWorkingTreeChanges(worktreePath) {
 function autoFinishReadyAgentBranches(repoRoot, options = {}) {
   const baseBranch = String(options.baseBranch || '').trim();
   const dryRun = Boolean(options.dryRun);
+  const waitForMerge = options.waitForMerge !== false;
   const excludedBranches = new Set(
     Array.isArray(options.excludeBranches)
       ? options.excludeBranches.map((branch) => String(branch || '').trim()).filter(Boolean)
@@ -2983,16 +3459,15 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
 
     summary.attempted += 1;
     const finishArgs = [
-      finishScript,
       '--branch',
       branch,
       '--base',
       baseBranch,
       '--via-pr',
-      '--wait-for-merge',
+      waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge',
       '--cleanup',
     ];
-    const finishResult = run('bash', finishArgs, { cwd: repoRoot });
+    const finishResult = runPackageAsset('branchFinish', finishArgs, { cwd: repoRoot });
     const combinedOutput = [finishResult.stdout || '', finishResult.stderr || ''].join('\n').trim();
 
     if (finishResult.status === 0) {
@@ -3145,9 +3620,9 @@ function printSetupRepoHints(repoRoot, baseBranch, repoLabel = '') {
     console.log(`[${TOOL_NAME}] Bootstrap commit${label}: git add . && git commit -m "bootstrap gitguardex"`);
     console.log(
       `[${TOOL_NAME}] First agent flow${label}: ` +
-      `bash scripts/agent-branch-start.sh "<task>" "codex" -> ` +
-      `python3 scripts/agent-file-locks.py claim --branch "$(git branch --show-current)" <file...> -> ` +
-      `bash scripts/agent-branch-finish.sh --branch "$(git branch --show-current)" --base ${baseBranch} --via-pr --wait-for-merge`,
+      `gx branch start "<task>" "codex" -> ` +
+      `gx locks claim --branch "$(git branch --show-current)" <file...> -> ` +
+      `gx branch finish --branch "$(git branch --show-current)" --base ${baseBranch} --via-pr --wait-for-merge`,
     );
   }
   if (!hasOrigin) {
@@ -3419,19 +3894,96 @@ function parseCleanupArgs(rawArgs) {
   return options;
 }
 
-function parseFinishArgs(rawArgs) {
+function parseMergeArgs(rawArgs) {
+  const options = {
+    target: process.cwd(),
+    base: '',
+    into: '',
+    branches: [],
+    task: '',
+    agent: '',
+  };
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === '--target') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--target requires a path value');
+      }
+      options.target = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--base') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--base requires a branch value');
+      }
+      options.base = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--into') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--into requires an agent/* branch value');
+      }
+      options.into = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--branch') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--branch requires an agent/* branch value');
+      }
+      options.branches.push(next);
+      index += 1;
+      continue;
+    }
+    if (arg === '--task') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--task requires a task value');
+      }
+      options.task = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--agent') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--agent requires an agent value');
+      }
+      options.agent = next;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (options.branches.length === 0) {
+    throw new Error('merge requires at least one --branch <agent/*> input');
+  }
+
+  return options;
+}
+
+function parseFinishArgs(rawArgs, defaults = {}) {
   const options = {
     target: process.cwd(),
     base: '',
     branch: '',
     all: false,
     dryRun: false,
-    waitForMerge: true,
-    cleanup: true,
+    waitForMerge: defaults.waitForMerge ?? true,
+    cleanup: defaults.cleanup ?? true,
     keepRemote: false,
     noAutoCommit: false,
     failFast: false,
     commitMessage: '',
+    mergeMode: defaults.mergeMode || 'pr',
   };
 
   for (let index = 0; index < rawArgs.length; index += 1) {
@@ -3488,6 +4040,26 @@ function parseFinishArgs(rawArgs) {
       options.waitForMerge = false;
       continue;
     }
+    if (arg === '--via-pr') {
+      options.mergeMode = 'pr';
+      continue;
+    }
+    if (arg === '--direct-only') {
+      options.mergeMode = 'direct';
+      continue;
+    }
+    if (arg === '--mode') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--mode requires a value');
+      }
+      if (!['auto', 'direct', 'pr'].includes(next)) {
+        throw new Error(`Invalid --mode value: ${next} (expected auto|direct|pr)`);
+      }
+      options.mergeMode = next;
+      index += 1;
+      continue;
+    }
     if (arg === '--cleanup') {
       options.cleanup = true;
       continue;
@@ -3652,7 +4224,7 @@ function claimLocksForAutoCommit(repoRoot, worktreePath, branch) {
   ]);
 
   if (changedFiles.length > 0) {
-    const claim = run('python3', [lockScript, 'claim', '--branch', branch, ...changedFiles], {
+    const claim = runPackageAsset('lockTool', ['claim', '--branch', branch, ...changedFiles], {
       cwd: repoRoot,
       stdio: 'pipe',
     });
@@ -3686,7 +4258,7 @@ function claimLocksForAutoCommit(repoRoot, worktreePath, branch) {
   ]);
 
   if (deletedFiles.length > 0) {
-    const allowDelete = run('python3', [lockScript, 'allow-delete', '--branch', branch, ...deletedFiles], {
+    const allowDelete = runPackageAsset('lockTool', ['allow-delete', '--branch', branch, ...deletedFiles], {
       cwd: repoRoot,
       stdio: 'pipe',
     });
@@ -4464,6 +5036,16 @@ function askGlobalInstallForMissing(options, missingPackages, missingLocalTools)
 }
 
 function installGlobalToolchain(options) {
+  const approval = resolveGlobalInstallApproval(options);
+  if (approval.source === 'flag' && !approval.approved) {
+    return {
+      status: 'skipped',
+      reason: approval.source,
+      missingPackages: [],
+      missingLocalTools: [],
+    };
+  }
+
   if (options.dryRun) {
     return { status: 'dry-run-skip' };
   }
@@ -4492,11 +5074,11 @@ function installGlobalToolchain(options) {
 
   const missingPackages = detection.ok ? detection.missing : [...GLOBAL_TOOLCHAIN_PACKAGES];
   const missingLocalTools = localCompanionTools.filter((tool) => tool.status !== 'active');
-  const approval = askGlobalInstallForMissing(options, missingPackages, missingLocalTools);
-  if (!approval.approved) {
+  const installApproval = askGlobalInstallForMissing(options, missingPackages, missingLocalTools);
+  if (!installApproval.approved) {
     return {
       status: 'skipped',
-      reason: approval.source,
+      reason: installApproval.source,
       missingPackages,
       missingLocalTools,
     };
@@ -4591,13 +5173,15 @@ function runInstallInternal(options) {
   for (const templateFile of TEMPLATE_FILES) {
     operations.push(copyTemplateFile(repoRoot, templateFile, Boolean(options.force), Boolean(options.dryRun)));
   }
+  for (const shim of SCRIPT_SHIMS) {
+    operations.push(ensureGeneratedScriptShim(repoRoot, shim, options));
+  }
+  for (const hookName of HOOK_NAMES) {
+    operations.push(ensureHookShim(repoRoot, hookName, options));
+  }
 
   operations.push(ensureLockRegistry(repoRoot, Boolean(options.dryRun)));
 
-  if (!options.skipPackageJson) {
-    operations.push(ensurePackageScripts(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
-  }
-
   if (!options.skipAgents) {
     operations.push(ensureAgentsSnippet(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
   }
@@ -4636,6 +5220,12 @@ function runFixInternal(options) {
   for (const templateFile of TEMPLATE_FILES) {
     operations.push(ensureTemplateFilePresent(repoRoot, templateFile, Boolean(options.dryRun)));
   }
+  for (const shim of SCRIPT_SHIMS) {
+    operations.push(ensureGeneratedScriptShim(repoRoot, shim, options));
+  }
+  for (const hookName of HOOK_NAMES) {
+    operations.push(ensureHookShim(repoRoot, hookName, options));
+  }
 
   operations.push(ensureLockRegistry(repoRoot, Boolean(options.dryRun)));
 
@@ -4665,10 +5255,6 @@ function runFixInternal(options) {
     }
   }
 
-  if (!options.skipPackageJson) {
-    operations.push(ensurePackageScripts(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
-  }
-
   if (!options.skipAgents) {
     operations.push(ensureAgentsSnippet(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
   }
@@ -4698,8 +5284,7 @@ function runScanInternal(options) {
   const requiredPaths = [
     ...OMX_SCAFFOLD_DIRECTORIES,
     ...Array.from(OMX_SCAFFOLD_FILES.keys()),
-    ...TEMPLATE_FILES.map((entry) => toDestinationPath(entry)),
-    LOCK_FILE_RELATIVE,
+    ...REQUIRED_WORKFLOW_FILES,
   ];
 
   for (const relativePath of requiredPaths) {
@@ -4834,21 +5419,34 @@ function printScanResult(scan, json = false) {
 
   if (scan.guardexEnabled === false) {
     console.log(
-      `[${TOOL_NAME}] Guardex is disabled for this repo (${describeGuardexRepoToggle(scan.guardexToggle)}).`,
+      colorizeDoctorOutput(
+        `[${TOOL_NAME}] Guardex is disabled for this repo (${describeGuardexRepoToggle(scan.guardexToggle)}).`,
+        'disabled',
+      ),
     );
     return;
   }
 
   if (scan.findings.length === 0) {
-    console.log(`[${TOOL_NAME}] ✅ No safety issues detected.`);
+    console.log(colorizeDoctorOutput(`[${TOOL_NAME}] ✅ No safety issues detected.`, 'safe'));
     return;
   }
 
   for (const item of scan.findings) {
     const target = item.path ? ` (${item.path})` : '';
-    console.log(`[${item.level.toUpperCase()}] ${item.code}${target}: ${item.message}`);
+    console.log(
+      colorizeDoctorOutput(
+        `[${item.level.toUpperCase()}] ${item.code}${target}: ${item.message}`,
+        item.level,
+      ),
+    );
   }
-  console.log(`[${TOOL_NAME}] Summary: ${scan.errors} error(s), ${scan.warnings} warning(s).`);
+  console.log(
+    colorizeDoctorOutput(
+      `[${TOOL_NAME}] Summary: ${scan.errors} error(s), ${scan.warnings} warning(s).`,
+      scan.errors > 0 ? 'error' : 'warn',
+    ),
+  );
 }
 
 function setExitCodeFromScan(scan) {
@@ -5127,31 +5725,38 @@ function doctor(rawArgs) {
 
     const repoResults = [];
     let aggregateExitCode = 0;
-    for (const repoPath of discoveredRepos) {
+    for (let repoIndex = 0; repoIndex < discoveredRepos.length; repoIndex += 1) {
+      const repoPath = discoveredRepos[repoIndex];
+      const progressLabel = `${repoIndex + 1}/${discoveredRepos.length}`;
       if (!options.json) {
-        console.log(`[${TOOL_NAME}] ── Doctor target: ${repoPath} ──`);
+        console.log(`[${TOOL_NAME}] ── Doctor target: ${repoPath} [${progressLabel}] ──`);
       }
 
-      const nestedResult = run(
-        process.execPath,
-        [
-          path.resolve(__filename),
-          'doctor',
-          '--single-repo',
-          '--target',
-          repoPath,
-          ...(options.dropStaleLocks ? [] : ['--keep-stale-locks']),
-          ...(options.skipAgents ? ['--skip-agents'] : []),
-          ...(options.skipPackageJson ? ['--skip-package-json'] : []),
-          ...(options.skipGitignore ? ['--no-gitignore'] : []),
-          ...(options.dryRun ? ['--dry-run'] : []),
-          // Recursive child doctor runs should report pending PR state immediately instead of blocking the parent loop.
-          '--no-wait-for-merge',
-          ...(options.json ? ['--json'] : []),
-          ...(options.allowProtectedBaseWrite ? ['--allow-protected-base-write'] : []),
-        ],
-        { cwd: topRepoRoot },
-      );
+      const childArgs = [
+        path.resolve(__filename),
+        'doctor',
+        '--single-repo',
+        '--target',
+        repoPath,
+        ...(options.dropStaleLocks ? [] : ['--keep-stale-locks']),
+        ...(options.skipAgents ? ['--skip-agents'] : []),
+        ...(options.skipPackageJson ? ['--skip-package-json'] : []),
+        ...(options.skipGitignore ? ['--no-gitignore'] : []),
+        ...(options.dryRun ? ['--dry-run'] : []),
+        // Recursive child doctor runs should report pending PR state immediately instead of blocking the parent loop.
+        '--no-wait-for-merge',
+        ...(options.verboseAutoFinish ? ['--verbose-auto-finish'] : []),
+        ...(options.json ? ['--json'] : []),
+        ...(options.allowProtectedBaseWrite ? ['--allow-protected-base-write'] : []),
+      ];
+      const startedAt = Date.now();
+      const nestedResult = options.json
+        ? run(process.execPath, childArgs, { cwd: topRepoRoot })
+        : cp.spawnSync(process.execPath, childArgs, {
+          cwd: topRepoRoot,
+          encoding: 'utf8',
+          stdio: 'inherit',
+        });
       if (isSpawnFailure(nestedResult)) {
         throw nestedResult.error;
       }
@@ -5181,9 +5786,12 @@ function doctor(rawArgs) {
             },
         );
       } else {
-        if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
-        if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
-        process.stdout.write('\n');
+        console.log(
+          `[${TOOL_NAME}] Doctor target complete: ${repoPath} [${progressLabel}] in ${formatElapsedDuration(Date.now() - startedAt)}.`,
+        );
+        if (repoIndex < discoveredRepos.length - 1) {
+          process.stdout.write('\n');
+        }
       }
     }
 
@@ -5232,6 +5840,7 @@ function doctor(rawArgs) {
     : autoFinishReadyAgentBranches(scanResult.repoRoot, {
       baseBranch: currentBaseBranch,
       dryRun: singleRepoOptions.dryRun,
+      waitForMerge: singleRepoOptions.waitForMerge,
     });
   const safe = scanResult.guardexEnabled === false || (scanResult.errors === 0 && scanResult.warnings === 0);
   const musafe = safe;
@@ -5273,21 +5882,18 @@ function doctor(rawArgs) {
     setExitCodeFromScan(scanResult);
     return;
   }
-  if (autoFinishSummary.enabled) {
-    console.log(
-      `[${TOOL_NAME}] Auto-finish sweep (base=${currentBaseBranch}): attempted=${autoFinishSummary.attempted}, completed=${autoFinishSummary.completed}, skipped=${autoFinishSummary.skipped}, failed=${autoFinishSummary.failed}`,
-    );
-    for (const detail of autoFinishSummary.details) {
-      console.log(`[${TOOL_NAME}]   ${detail}`);
-    }
-  } else if (autoFinishSummary.details.length > 0) {
-    console.log(`[${TOOL_NAME}] ${autoFinishSummary.details[0]}`);
-  }
+  printAutoFinishSummary(autoFinishSummary, {
+    baseBranch: currentBaseBranch,
+    verbose: singleRepoOptions.verboseAutoFinish,
+  });
   if (safe) {
-    console.log(`[${TOOL_NAME}] ✅ Repo is fully safe.`);
+    console.log(colorizeDoctorOutput(`[${TOOL_NAME}] ✅ Repo is fully safe.`, 'safe'));
   } else {
     console.log(
-      `[${TOOL_NAME}] ⚠️ Repo is not fully safe yet (${scanResult.errors} error(s), ${scanResult.warnings} warning(s)).`,
+      colorizeDoctorOutput(
+        `[${TOOL_NAME}] ⚠️ Repo is not fully safe yet (${scanResult.errors} error(s), ${scanResult.warnings} warning(s)).`,
+        scanResult.errors > 0 ? 'unsafe' : 'warn',
+      ),
     );
   }
   setExitCodeFromScan(scanResult);
@@ -6297,17 +6903,18 @@ function doctorAudit(rawArgs) {
 
   const packagePath = path.join(repoRoot, 'package.json');
   if (!fs.existsSync(packagePath)) {
-    warn('package.json not found (npm helper scripts cannot be verified)');
+    warn('package.json not found (legacy agent:* script drift cannot be checked)');
   } else {
     try {
       const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
       const scripts = pkg.scripts || {};
-      for (const [name, expectedValue] of Object.entries(REQUIRED_PACKAGE_SCRIPTS)) {
-        if (scripts[name] !== expectedValue) {
-          fail(`package.json script mismatch for "${name}"`);
-        } else {
-          ok(`package.json script "${name}" is configured`);
-        }
+      const legacyAgentScripts = Object.entries(LEGACY_MANAGED_PACKAGE_SCRIPTS)
+        .filter(([name, expectedValue]) => scripts[name] === expectedValue)
+        .map(([name]) => name);
+      if (legacyAgentScripts.length > 0) {
+        warn(`legacy agent:* package.json scripts remain (${legacyAgentScripts.join(', ')}); run '${SHORT_TOOL_NAME} migrate' to remove them`);
+      } else {
+        ok('package.json does not contain Guardex-managed agent:* helper scripts');
       }
     } catch (error) {
       fail(`package.json is invalid JSON: ${error.message}`);
@@ -6389,6 +6996,167 @@ function prompt(rawArgs) {
   return copyPrompt();
 }
 
+function printStandaloneOperations(title, rootLabel, operations, dryRun = false) {
+  console.log(`[${TOOL_NAME}] ${title}: ${rootLabel}`);
+  for (const operation of operations) {
+    const note = operation.note ? ` (${operation.note})` : '';
+    console.log(`  - ${operation.status.padEnd(12)} ${operation.file}${note}`);
+  }
+  if (dryRun) {
+    console.log(`[${TOOL_NAME}] Dry run complete. No files were modified.`);
+  }
+}
+
+function branch(rawArgs) {
+  const [subcommand, ...rest] = rawArgs;
+  if (subcommand === 'start') {
+    const { target, passthrough } = extractTargetedArgs(rest);
+    invokePackageAsset('branchStart', passthrough, { cwd: resolveRepoRoot(target) });
+    return;
+  }
+  if (subcommand === 'finish') {
+    const { target, passthrough } = extractTargetedArgs(rest);
+    invokePackageAsset('branchFinish', passthrough, { cwd: resolveRepoRoot(target) });
+    return;
+  }
+  if (subcommand === 'merge') return merge(rest);
+  throw new Error(
+    `Usage: ${SHORT_TOOL_NAME} branch <start|finish|merge> [options] ` +
+    `(examples: '${SHORT_TOOL_NAME} branch start "<task>" "<agent>"', '${SHORT_TOOL_NAME} branch finish --branch <agent/...>')`,
+  );
+}
+
+function locks(rawArgs) {
+  const { target, passthrough } = extractTargetedArgs(rawArgs);
+  const result = runPackageAsset('lockTool', passthrough, { cwd: resolveRepoRoot(target) });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exitCode = result.status;
+}
+
+function worktree(rawArgs) {
+  const [subcommand, ...rest] = rawArgs;
+  if (subcommand === 'prune') {
+    const { target, passthrough } = extractTargetedArgs(rest);
+    invokePackageAsset('worktreePrune', passthrough, { cwd: resolveRepoRoot(target) });
+    return;
+  }
+  throw new Error(`Usage: ${SHORT_TOOL_NAME} worktree prune [cleanup-options]`);
+}
+
+function hook(rawArgs) {
+  const [subcommand, ...rest] = rawArgs;
+  if (subcommand === 'run') {
+    const [hookName, ...hookArgs] = rest;
+    if (!HOOK_NAMES.includes(hookName)) {
+      throw new Error(`Unknown hook name: ${hookName || '(missing)'}`);
+    }
+    const { target, passthrough } = extractTargetedArgs(hookArgs);
+    const hookAssetPath = path.join(TEMPLATE_ROOT, 'githooks', hookName);
+    const result = run('bash', [hookAssetPath, ...passthrough], {
+      cwd: resolveRepoRoot(target),
+      stdio: hookName === 'pre-push' ? 'inherit' : 'pipe',
+      env: packageAssetEnv(),
+    });
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    process.exitCode = result.status;
+    return;
+  }
+  if (subcommand === 'install') {
+    const { target, passthrough } = extractTargetedArgs(rest);
+    if (passthrough.length > 0) {
+      throw new Error(`Unknown hook install option: ${passthrough[0]}`);
+    }
+    const repoRoot = resolveRepoRoot(target);
+    const hookResult = configureHooks(repoRoot, false);
+    console.log(`[${TOOL_NAME}] Hook install target: ${repoRoot}`);
+    console.log(`  - hooksPath    ${hookResult.status} ${hookResult.key}=${hookResult.value}`);
+    process.exitCode = 0;
+    return;
+  }
+  throw new Error(`Usage: ${SHORT_TOOL_NAME} hook <run|install> ...`);
+}
+
+function internal(rawArgs) {
+  const [subcommand, assetKey, ...rest] = rawArgs;
+  if (subcommand !== 'run-shell') {
+    throw new Error(`Unknown internal command: ${subcommand || '(missing)'}`);
+  }
+  const { target, passthrough } = extractTargetedArgs(rest);
+  const result = runPackageAsset(assetKey, passthrough, { cwd: resolveRepoRoot(target) });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exitCode = result.status;
+}
+
+function installAgentSkills(rawArgs) {
+  let dryRun = false;
+  let force = false;
+  for (const arg of rawArgs) {
+    if (arg === '--dry-run') {
+      dryRun = true;
+      continue;
+    }
+    if (arg === '--force') {
+      force = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  const operations = USER_LEVEL_SKILL_ASSETS.map((asset) => installUserLevelAsset(asset, { dryRun, force }));
+  printStandaloneOperations('User-level Guardex skills', GUARDEX_HOME_DIR, operations, dryRun);
+  process.exitCode = 0;
+}
+
+function migrate(rawArgs) {
+  const { target, passthrough } = extractTargetedArgs(rawArgs);
+  let dryRun = false;
+  let force = false;
+  let installSkills = false;
+  for (const arg of passthrough) {
+    if (arg === '--dry-run') {
+      dryRun = true;
+      continue;
+    }
+    if (arg === '--force') {
+      force = true;
+      continue;
+    }
+    if (arg === '--install-agent-skills') {
+      installSkills = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  const repoRoot = resolveRepoRoot(target);
+  const fixPayload = runFixInternal({
+    target: repoRoot,
+    dryRun,
+    force,
+    skipAgents: false,
+    skipPackageJson: true,
+    skipGitignore: false,
+    dropStaleLocks: true,
+  });
+  printOperations('Migrate/fix', fixPayload, dryRun);
+
+  if (installSkills) {
+    const skillOps = USER_LEVEL_SKILL_ASSETS.map((asset) => installUserLevelAsset(asset, { dryRun, force }));
+    printStandaloneOperations('Migrate/install-agent-skills', GUARDEX_HOME_DIR, skillOps, dryRun);
+  }
+
+  const removableLegacyFiles = LEGACY_MANAGED_REPO_FILES.filter(
+    (relativePath) => !REQUIRED_WORKFLOW_FILES.includes(relativePath),
+  );
+  const removalOps = removableLegacyFiles.map((relativePath) => removeLegacyManagedRepoFile(repoRoot, relativePath, { dryRun, force }));
+  removalOps.push(removeLegacyPackageScripts(repoRoot, dryRun));
+  printStandaloneOperations('Migrate/cleanup', repoRoot, removalOps, dryRun);
+  process.exitCode = 0;
+}
+
 function cleanup(rawArgs) {
   const options = parseCleanupArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
@@ -6397,7 +7165,7 @@ function cleanup(rawArgs) {
     throw new Error(`Missing cleanup script: ${pruneScript}. Run '${SHORT_TOOL_NAME} setup' first.`);
   }
 
-  const args = [pruneScript];
+  const args = [];
   if (options.base) {
     args.push('--base', options.base);
   }
@@ -6428,7 +7196,7 @@ function cleanup(rawArgs) {
   }
 
   const runCleanupCycle = () => {
-    const runResult = run('bash', args, { cwd: repoRoot, stdio: 'inherit' });
+    const runResult = runPackageAsset('worktreePrune', args, { cwd: repoRoot, stdio: 'inherit' });
     if (runResult.status !== 0) {
       throw new Error('Cleanup command failed');
     }
@@ -6458,8 +7226,48 @@ function cleanup(rawArgs) {
   process.exitCode = 0;
 }
 
-function finish(rawArgs) {
-  const options = parseFinishArgs(rawArgs);
+function merge(rawArgs) {
+  const options = parseMergeArgs(rawArgs);
+  const repoRoot = resolveRepoRoot(options.target);
+  const mergeScript = path.join(repoRoot, 'scripts', 'agent-branch-merge.sh');
+
+  if (!fs.existsSync(mergeScript)) {
+    throw new Error(`Missing merge script: ${mergeScript}. Run '${SHORT_TOOL_NAME} setup' first.`);
+  }
+
+  const args = [];
+  if (options.base) {
+    args.push('--base', options.base);
+  }
+  if (options.into) {
+    args.push('--into', options.into);
+  }
+  if (options.task) {
+    args.push('--task', options.task);
+  }
+  if (options.agent) {
+    args.push('--agent', options.agent);
+  }
+  for (const branch of options.branches) {
+    args.push('--branch', branch);
+  }
+
+  const mergeResult = runPackageAsset('branchMerge', args, { cwd: repoRoot, stdio: 'pipe' });
+  if (mergeResult.stdout) {
+    process.stdout.write(mergeResult.stdout);
+  }
+  if (mergeResult.stderr) {
+    process.stderr.write(mergeResult.stderr);
+  }
+  if (mergeResult.status !== 0) {
+    throw new Error(`merge command failed with status ${mergeResult.status}`);
+  }
+
+  process.exitCode = 0;
+}
+
+function finish(rawArgs, defaults = {}) {
+  const options = parseFinishArgs(rawArgs, defaults);
   const repoRoot = resolveRepoRoot(options.target);
   const finishScript = path.join(repoRoot, 'scripts', 'agent-branch-finish.sh');
 
@@ -6530,26 +7338,31 @@ function finish(rawArgs) {
       }
 
       const finishArgs = [
-        finishScript,
         '--branch',
         branch,
         '--base',
         baseBranch,
-        '--via-pr',
         options.waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge',
         options.cleanup ? '--cleanup' : '--no-cleanup',
       ];
+      if (options.mergeMode === 'pr') {
+        finishArgs.push('--via-pr');
+      } else if (options.mergeMode === 'direct') {
+        finishArgs.push('--direct-only');
+      } else {
+        finishArgs.push('--mode', 'auto');
+      }
       if (options.keepRemote) {
         finishArgs.push('--keep-remote-branch');
       }
 
       if (options.dryRun) {
-        console.log(`[${TOOL_NAME}] [dry-run] Would run: bash ${finishArgs.join(' ')}`);
+        console.log(`[${TOOL_NAME}] [dry-run] Would run: gx branch finish ${finishArgs.join(' ')}`);
         succeeded += 1;
         continue;
       }
 
-      const finishResult = run('bash', finishArgs, { cwd: repoRoot, stdio: 'pipe' });
+      const finishResult = runPackageAsset('branchFinish', finishArgs, { cwd: repoRoot, stdio: 'pipe' });
       if (finishResult.stdout) {
         process.stdout.write(finishResult.stdout);
       }
@@ -6943,7 +7756,15 @@ function main() {
 
   if (command === 'prompt') return prompt(rest);
   if (command === 'doctor') return doctor(rest);
+  if (command === 'branch') return branch(rest);
+  if (command === 'locks') return locks(rest);
+  if (command === 'worktree') return worktree(rest);
+  if (command === 'hook') return hook(rest);
+  if (command === 'migrate') return migrate(rest);
+  if (command === 'install-agent-skills') return installAgentSkills(rest);
+  if (command === 'internal') return internal(rest);
   if (command === 'agents') return agents(rest);
+  if (command === 'merge') return merge(rest);
   if (command === 'finish') return finish(rest);
   if (command === 'report') return report(rest);
   if (command === 'protect') return protect(rest);