@imdeadpool/guardex 5.0.9 → 5.0.12

package/README.md

@@ -1,8 +1,8 @@
 # GuardeX — Guardian T-Rex for your repo
 
 [![npm version](https://img.shields.io/npm/v/%40imdeadpool%2Fguardex?color=cb3837&logo=npm)](https://www.npmjs.com/package/@imdeadpool/guardex)
-[![CI](https://github.com/recodeecom/multiagent-safety/actions/workflows/ci.yml/badge.svg)](https://github.com/recodeecom/multiagent-safety/actions/workflows/ci.yml)
-[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/recodeecom/multiagent-safety/badge)](https://securityscorecards.dev/viewer/?uri=github.com/recodeecom/multiagent-safety)
+[![CI](https://github.com/recodeee/guardex/actions/workflows/ci.yml/badge.svg)](https://github.com/recodeee/guardex/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/recodeee/guardex/badge)](https://securityscorecards.dev/viewer/?uri=github.com/recodeee/guardex)
 
 GuardeX is a safety layer for parallel Codex/agent work in git repos.
 
@@ -17,7 +17,7 @@ Progress became **de-progressive**: more activity, less real forward movement.
 
 GuardeX exists to stop that loop.
 
-![Multi-agent dashboard example](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/dashboard-multi-agent.png)
+![Multi-agent dashboard example](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/dashboard-multi-agent.png)
 
 ```mermaid
 flowchart LR
@@ -81,23 +81,23 @@ gx finish --all
 
 ### Setup status
 
-![gx setup behavior screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/setup-success.svg)
+![gx setup behavior screenshot](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/setup-success.svg)
 
 ### Service logs/status
 
-![gx status logs screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/status-tools-logs.svg)
+![gx status logs screenshot](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/status-tools-logs.svg)
 
 ### Branch/worktree start protocol
 
-![gx branch start protocol screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-branch-start.svg)
+![gx branch start protocol screenshot](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/workflow-branch-start.svg)
 
 ### Lock + delete guard protocol
 
-![gx lock and delete guard screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-lock-guard.svg)
+![gx lock and delete guard screenshot](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/workflow-lock-guard.svg)
 
 ### Real VS Code Source Control layout (exact screenshot)
 
-![Real VS Code Source Control layout](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-vscode-source-control-exact.png)
+![Real VS Code Source Control layout](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/workflow-vscode-source-control-exact.png)
 
 ## Copy-paste: common commands
 
@@ -124,15 +124,24 @@ gx sync
 # continuously monitor open PRs targeting current branch and dispatch codex-agent review/merge tasks
 gx review --interval 30
 
+# start both background bots for this repo (review + cleanup)
+gx agents start
+
+# stop both background bots for this repo
+gx agents stop
+
 # auto-commit finished agent branches and open/merge PR flow in one pass
 gx finish --all
 
 # cleanup merged agent branches and hide clean stale agent worktrees
 gx cleanup
 
+# run continuous stale-branch cleanup bot (default idle threshold: 10 minutes)
+gx cleanup --watch --interval 60
+
 # scan/report
 gx scan
-gx report scorecard --repo github.com/recodeecom/multiagent-safety
+gx report scorecard --repo github.com/recodeee/guardex
 ```
 
 ### Continuous Codex PR monitor (local codex-auth session)
@@ -152,6 +161,37 @@ Useful flags:
 
 Note: the monitor dispatches Codex through explicit `--task/--agent/--base` flags for compatibility with both older and newer `scripts/codex-agent.sh` argument parsing.
 
+### Continuous stale branch cleanup bot
+
+Use this to auto-prune idle `agent/*` worktrees created by Codex while keeping active worktrees untouched.
+
+```sh
+# watch cleanup loop every minute (default idle threshold is 10 minutes when --watch is enabled)
+gx cleanup --watch --interval 60
+
+# one-shot cleanup for branches idle at least 10 minutes
+gx cleanup --idle-minutes 10
+
+# run a single watch cycle (helpful for cron/CI checks)
+gx cleanup --watch --once --interval 60
+```
+
+### Repo Agent Supervisor (start both bots with one command)
+
+```sh
+# starts review bot + cleanup bot in background for the current repo
+gx agents start
+
+# optional tuning
+gx agents start --review-interval 30 --cleanup-interval 60 --idle-minutes 10
+
+# show whether both bots are running for this repo
+gx agents status
+
+# stop both bots and clear repo-local state
+gx agents stop
+```
+
 ## Important behavior defaults
 
 - No command defaults to `gx status`.
@@ -201,6 +241,40 @@ gh --version
 gh auth status
 ```
 
+## Optional GitHub Apps: fork sync + PR review
+
+### Pull app (Probot fork sync)
+
+GuardeX setup now installs a starter file at `.github/pull.yml.example`.
+
+To enable fork auto-sync:
+
+```sh
+cp .github/pull.yml.example .github/pull.yml
+```
+
+Then edit `.github/pull.yml`:
+
+- set `rules[].base` to your fork branch (`main`, `master`, or `dev`)
+- set `rules[].upstream` to `<upstream-owner>:<branch>`
+
+Install the app: <https://github.com/apps/pull>  
+Validate config: `https://pull.git.ci/check/<owner>/<repo>`
+
+### CR-GPT code review app
+
+Install app: <https://github.com/apps/cr-gpt>
+
+`gx setup` also installs `.github/workflows/cr.yml` (GitHub Actions review workflow).
+
+Then in your repo:
+
+1. `Settings -> Secrets and variables -> Actions`
+2. open `Variables`
+3. add `OPENAI_API_KEY`
+
+After that, the app reviews new and updated pull requests automatically.
+
 ## Companion dependency: `codex-auth` account switcher
 
 For multi-identity Codex workflows, GuardeX pairs with
@@ -236,6 +310,8 @@ scripts/openspec/init-plan-workspace.sh
 .githooks/pre-push
 .codex/skills/guardex/SKILL.md
 .claude/commands/guardex.md
+.github/pull.yml.example
+.github/workflows/cr.yml
 .omx/state/agent-file-locks.json
 ```
 
@@ -247,6 +323,23 @@ If you enabled global OpenSpec install during setup (`@fission-ai/openspec`), us
 
 - [`docs/openspec-getting-started.md`](./docs/openspec-getting-started.md)
 
+Default core flow:
+
+```text
+/opsx:propose <change-name> -> /opsx:apply -> /opsx:archive
+```
+
+Optional expanded flow:
+
+```sh
+openspec config profile <profile-name>
+openspec update
+```
+
+```text
+/opsx:new <change-name> -> /opsx:ff or /opsx:continue -> /opsx:apply -> /opsx:verify -> /opsx:archive
+```
+
 ### OpenSpec in agent sub-branches
 
 - `scripts/codex-agent.sh` enforces an OpenSpec workspace before it launches Codex in each sandbox branch/worktree.
@@ -271,6 +364,21 @@ npm pack --dry-run
 
 ## Release notes
 
+### v5.0.12
+
+- Bumped package version from `5.0.11` to `5.0.12` for the next npm publish.
+- Updated repository metadata and README links to the renamed GitHub repository (`recodeee/guardex`).
+
+### v5.0.11
+
+- Updated the managed AGENTS contract wording to use `GX` naming and added an explicit OMX completion policy requiring commit + push + PR creation/update at task completion.
+- Ensured `gx install` explicitly configures the managed `AGENTS.md` policy block and added regression coverage for this install-path behavior.
+- Bumped package version from `5.0.10` to `5.0.11` for the next npm publish.
+
+### v5.0.10
+
+- Bumped package version from `5.0.9` to `5.0.10` for the next npm publish.
+
 ### v5.0.9
 
 - Enforced OpenSpec workspace bootstrap for sandbox agent execution: `scripts/codex-agent.sh` now initializes `openspec/plan/<agent-branch-slug>/` before launching Codex, and `scripts/agent-branch-start.sh` supports `MUSAFETY_OPENSPEC_AUTO_INIT` plus `MUSAFETY_OPENSPEC_PLAN_SLUG`.

package/bin/multiagent-safety.js

@@ -50,7 +50,10 @@ const TEMPLATE_FILES = [
   'githooks/pre-commit',
   'githooks/pre-push',
   'codex/skills/guardex/SKILL.md',
+  'codex/skills/guardex-merge-skills-to-dev/SKILL.md',
   'claude/commands/guardex.md',
+  'github/pull.yml.example',
+  'github/workflows/cr.yml',
 ];
 
 const EXECUTABLE_RELATIVE_PATHS = new Set([
@@ -78,6 +81,7 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
 ]);
 
 const LOCK_FILE_RELATIVE = '.omx/state/agent-file-locks.json';
+const AGENTS_BOTS_STATE_RELATIVE = '.omx/state/agents-bots.json';
 const AGENTS_MARKER_START = '<!-- multiagent-safety:START -->';
 const AGENTS_MARKER_END = '<!-- multiagent-safety:END -->';
 const GITIGNORE_MARKER_START = '# multiagent-safety:START';
@@ -96,6 +100,7 @@ const MANAGED_GITIGNORE_PATHS = [
   '.githooks/pre-push',
   'oh-my-codex/',
   '.codex/skills/guardex/SKILL.md',
+  '.codex/skills/guardex-merge-skills-to-dev/SKILL.md',
   '.claude/commands/guardex.md',
   LOCK_FILE_RELATIVE,
 ];
@@ -128,6 +133,7 @@ const SUGGESTIBLE_COMMANDS = [
   'init',
   'doctor',
   'review',
+  'agents',
   'finish',
   'report',
   'copy-prompt',
@@ -154,7 +160,8 @@ const CLI_COMMAND_DESCRIPTIONS = [
   ['copy-commands', 'Print setup checklist as executable commands only'],
   ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
   ['sync', 'Check or sync agent branches with origin/<base>'],
-  ['cleanup', 'Cleanup merged agent branches/worktrees (local + remote)'],
+  ['cleanup', 'Cleanup agent branches/worktrees (supports idle watch mode)'],
+  ['agents', 'Start/stop repo-scoped review + cleanup bots'],
   ['install', 'Install templates/locks/hooks without running full setup (supports --no-gitignore)'],
   ['fix', 'Repair broken or missing guardrail files/config (supports --no-gitignore)'],
   ['scan', 'Report safety issues and exit non-zero on findings'],
@@ -165,6 +172,7 @@ const CLI_COMMAND_DESCRIPTIONS = [
 ];
 const AGENT_BOT_DESCRIPTIONS = [
   ['review', 'Start PR monitor + codex-agent review flow (default interval: 30s)'],
+  ['agents', 'Start/stop both review and cleanup bots for this repo'],
 ];
 
 const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-Rex for your repo) in this repository for Codex or Claude.
@@ -203,18 +211,48 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
    - To finalize all completed agent branches in one pass:
      gx finish --all
 
-6) Optional: create OpenSpec planning workspace:
+6) OpenSpec default change flow (core profile):
+   /opsx:propose <change-name>
+   /opsx:apply
+   /opsx:archive
+   - Full guide: docs/openspec-getting-started.md
+
+7) Optional: enable expanded OpenSpec workflow commands:
+   openspec config profile <profile-name>
+   openspec update
+   - Expanded path: /opsx:new -> /opsx:ff or /opsx:continue -> /opsx:apply -> /opsx:verify -> /opsx:archive
+
+8) Optional: create OpenSpec planning workspace:
    bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
 
-7) Optional: protect extra branches:
+9) Optional: protect extra branches:
    gx protect add release staging
 
-8) Optional: sync your current agent branch with latest base branch:
+10) Optional: sync your current agent branch with latest base branch:
    gx sync --check
    gx sync
 
-9) Optional (GitHub remote cleanup): enable:
+11) Optional (GitHub remote cleanup): enable:
    Settings -> General -> Pull Requests -> Automatically delete head branches
+
+12) Optional (fork sync with Pull app):
+   cp .github/pull.yml.example .github/pull.yml
+   # then edit .github/pull.yml:
+   # - set rules[].base to your fork branch (main/master/dev)
+   # - set rules[].upstream to upstream-owner:branch
+   # install app: https://github.com/apps/pull
+   # validate config: https://pull.git.ci/check/<owner>/<repo>
+
+13) Optional (PR review bot with cr-gpt GitHub App):
+   - install app: https://github.com/apps/cr-gpt
+   - in GitHub repo Settings -> Secrets and variables -> Actions -> Variables:
+     add OPENAI_API_KEY (your API key)
+   - the app reviews new/updated pull requests automatically
+
+14) Optional: test PR review action workflow
+   - gx setup installs .github/workflows/cr.yml
+   - open or update a PR
+   - check Actions -> "Code Review" run logs + PR timeline comments
 `;
 
 const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
@@ -229,9 +267,12 @@ bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)
 gx finish --all
 gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
 bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
+openspec config profile <profile-name>
+openspec update
 gx protect add release staging
 gx sync --check
 gx sync
+cp .github/pull.yml.example .github/pull.yml
 `;
 
 const SCORECARD_RISK_BY_CHECK = {
@@ -435,6 +476,9 @@ function toDestinationPath(relativeTemplatePath) {
   if (relativeTemplatePath.startsWith('claude/')) {
     return `.${relativeTemplatePath}`;
   }
+  if (relativeTemplatePath.startsWith('github/')) {
+    return `.${relativeTemplatePath}`;
+  }
   throw new Error(`Unsupported template path: ${relativeTemplatePath}`);
 }
 
@@ -1567,6 +1611,69 @@ function parseReviewArgs(rawArgs) {
   };
 }
 
+function parseAgentsArgs(rawArgs) {
+  const parsed = parseTargetFlag(rawArgs, process.cwd());
+  const [subcommandRaw = '', ...rest] = parsed.args;
+  const subcommand = subcommandRaw || 'status';
+  const options = {
+    target: parsed.target,
+    subcommand,
+    reviewIntervalSeconds: 30,
+    cleanupIntervalSeconds: 60,
+    idleMinutes: 10,
+  };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (arg === '--review-interval') {
+      const next = rest[index + 1];
+      if (!next) {
+        throw new Error('--review-interval requires an integer seconds value');
+      }
+      const parsedValue = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsedValue) || parsedValue < 5) {
+        throw new Error('--review-interval must be an integer >= 5 seconds');
+      }
+      options.reviewIntervalSeconds = parsedValue;
+      index += 1;
+      continue;
+    }
+    if (arg === '--cleanup-interval') {
+      const next = rest[index + 1];
+      if (!next) {
+        throw new Error('--cleanup-interval requires an integer seconds value');
+      }
+      const parsedValue = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsedValue) || parsedValue < 5) {
+        throw new Error('--cleanup-interval must be an integer >= 5 seconds');
+      }
+      options.cleanupIntervalSeconds = parsedValue;
+      index += 1;
+      continue;
+    }
+    if (arg === '--idle-minutes') {
+      const next = rest[index + 1];
+      if (!next) {
+        throw new Error('--idle-minutes requires an integer minutes value');
+      }
+      const parsedValue = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsedValue) || parsedValue < 1) {
+        throw new Error('--idle-minutes must be an integer >= 1');
+      }
+      options.idleMinutes = parsedValue;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (!['start', 'stop', 'status'].includes(options.subcommand)) {
+    throw new Error(`Unknown agents subcommand: ${options.subcommand}`);
+  }
+
+  return options;
+}
+
 function parseReportArgs(rawArgs) {
   const options = {
     target: process.cwd(),
@@ -2276,6 +2383,10 @@ function parseCleanupArgs(rawArgs) {
     forceDirty: false,
     keepRemote: false,
     keepCleanWorktrees: false,
+    idleMinutes: 0,
+    watch: false,
+    intervalSeconds: 60,
+    once: false,
   };
 
   for (let index = 0; index < rawArgs.length; index += 1) {
@@ -2323,9 +2434,47 @@ function parseCleanupArgs(rawArgs) {
       options.keepCleanWorktrees = true;
       continue;
     }
+    if (arg === '--idle-minutes') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--idle-minutes requires an integer value');
+      }
+      const parsed = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error('--idle-minutes must be an integer >= 0');
+      }
+      options.idleMinutes = parsed;
+      index += 1;
+      continue;
+    }
+    if (arg === '--watch') {
+      options.watch = true;
+      continue;
+    }
+    if (arg === '--interval') {
+      const next = rawArgs[index + 1];
+      if (!next) {
+        throw new Error('--interval requires an integer seconds value');
+      }
+      const parsed = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsed) || parsed < 5) {
+        throw new Error('--interval must be an integer >= 5 seconds');
+      }
+      options.intervalSeconds = parsed;
+      index += 1;
+      continue;
+    }
+    if (arg === '--once') {
+      options.once = true;
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}`);
   }
 
+  if (options.watch && options.idleMinutes === 0) {
+    options.idleMinutes = 10;
+  }
+
   return options;
 }
 
@@ -3485,6 +3634,9 @@ function install(rawArgs) {
   printOperations('Install target', payload, options.dryRun);
 
   if (!options.dryRun) {
+    if (!options.skipAgents) {
+      console.log(`[${TOOL_NAME}] AGENTS.md managed policy block is configured by install.`);
+    }
     console.log(`[${TOOL_NAME}] Installed. Next step: ${TOOL_NAME} setup`);
   }
 
@@ -3624,6 +3776,263 @@ function review(rawArgs) {
   process.exitCode = typeof result.status === 'number' ? result.status : 1;
 }
 
+function agentsStatePathForRepo(repoRoot) {
+  return path.join(repoRoot, AGENTS_BOTS_STATE_RELATIVE);
+}
+
+function readAgentsState(repoRoot) {
+  const statePath = agentsStatePathForRepo(repoRoot);
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function writeAgentsState(repoRoot, state) {
+  const statePath = agentsStatePathForRepo(repoRoot);
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+
+function processAlive(pid) {
+  const normalizedPid = Number.parseInt(String(pid || ''), 10);
+  if (!Number.isInteger(normalizedPid) || normalizedPid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(normalizedPid, 0);
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}
+
+function sleepSeconds(seconds) {
+  const result = run('sleep', [String(seconds)]);
+  if (isSpawnFailure(result) || result.status !== 0) {
+    throw new Error(`sleep command failed for ${seconds}s`);
+  }
+}
+
+function readProcessCommand(pid) {
+  const result = run('ps', ['-o', 'command=', '-p', String(pid)]);
+  if (isSpawnFailure(result) || result.status !== 0) {
+    return '';
+  }
+  return String(result.stdout || '').trim();
+}
+
+function stopAgentProcessByPid(pid, expectedToken = '') {
+  const normalizedPid = Number.parseInt(String(pid || ''), 10);
+  if (!Number.isInteger(normalizedPid) || normalizedPid <= 0) {
+    return { status: 'invalid', pid: normalizedPid };
+  }
+  if (!processAlive(normalizedPid)) {
+    return { status: 'not-running', pid: normalizedPid };
+  }
+
+  if (expectedToken) {
+    const cmdline = readProcessCommand(normalizedPid);
+    if (cmdline && !cmdline.includes(expectedToken)) {
+      return { status: 'mismatch', pid: normalizedPid, command: cmdline };
+    }
+  }
+
+  try {
+    process.kill(-normalizedPid, 'SIGTERM');
+  } catch (_error) {
+    try {
+      process.kill(normalizedPid, 'SIGTERM');
+    } catch (_err) {
+      return { status: 'term-failed', pid: normalizedPid };
+    }
+  }
+
+  const deadline = Date.now() + 3_000;
+  while (Date.now() < deadline) {
+    if (!processAlive(normalizedPid)) {
+      return { status: 'stopped', pid: normalizedPid };
+    }
+    sleepSeconds(0.1);
+  }
+
+  try {
+    process.kill(-normalizedPid, 'SIGKILL');
+  } catch (_error) {
+    try {
+      process.kill(normalizedPid, 'SIGKILL');
+    } catch (_err) {
+      return { status: 'kill-failed', pid: normalizedPid };
+    }
+  }
+  sleepSeconds(0.1);
+
+  return {
+    status: processAlive(normalizedPid) ? 'kill-failed' : 'stopped',
+    pid: normalizedPid,
+  };
+}
+
+function spawnDetachedAgentProcess({ command, args, cwd, logPath }) {
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const logHandle = fs.openSync(logPath, 'a');
+  fs.writeSync(
+    logHandle,
+    `[${new Date().toISOString()}] spawn: ${command} ${args.join(' ')}\n`,
+  );
+  const child = cp.spawn(command, args, {
+    cwd,
+    detached: true,
+    stdio: ['ignore', logHandle, logHandle],
+    env: process.env,
+  });
+  fs.closeSync(logHandle);
+  if (child.error) {
+    throw child.error;
+  }
+  child.unref();
+  const pid = Number.parseInt(String(child.pid || ''), 10);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    throw new Error(`Failed to spawn detached process for ${command}`);
+  }
+  return pid;
+}
+
+function agents(rawArgs) {
+  const options = parseAgentsArgs(rawArgs);
+  const repoRoot = resolveRepoRoot(options.target);
+  const reviewScriptPath = path.join(repoRoot, 'scripts', 'review-bot-watch.sh');
+  const pruneScriptPath = path.join(repoRoot, 'scripts', 'agent-worktree-prune.sh');
+  const statePath = agentsStatePathForRepo(repoRoot);
+
+  if (options.subcommand === 'start') {
+    if (!fs.existsSync(reviewScriptPath)) {
+      throw new Error(
+        `Missing review bot script: ${reviewScriptPath}\n` +
+          `Run '${SHORT_TOOL_NAME} setup --target ${repoRoot}' then '${SHORT_TOOL_NAME} doctor --target ${repoRoot}'.`,
+      );
+    }
+    if (!fs.existsSync(pruneScriptPath)) {
+      throw new Error(
+        `Missing cleanup script: ${pruneScriptPath}\n` +
+          `Run '${SHORT_TOOL_NAME} setup --target ${repoRoot}' then '${SHORT_TOOL_NAME} doctor --target ${repoRoot}'.`,
+      );
+    }
+
+    const existingState = readAgentsState(repoRoot);
+    const existingReviewPid = Number.parseInt(String(existingState?.review?.pid || ''), 10);
+    const existingCleanupPid = Number.parseInt(String(existingState?.cleanup?.pid || ''), 10);
+    const reviewRunning = processAlive(existingReviewPid);
+    const cleanupRunning = processAlive(existingCleanupPid);
+
+    if (reviewRunning && cleanupRunning) {
+      console.log(
+        `[${TOOL_NAME}] Repo agents already running (review pid=${existingReviewPid}, cleanup pid=${existingCleanupPid}).`,
+      );
+      process.exitCode = 0;
+      return;
+    }
+
+    if (reviewRunning) {
+      stopAgentProcessByPid(existingReviewPid, 'review-bot-watch.sh');
+    }
+    if (cleanupRunning) {
+      stopAgentProcessByPid(existingCleanupPid, `${path.basename(__filename)} cleanup`);
+    }
+
+    const reviewLogPath = path.join(repoRoot, '.omx', 'logs', 'agent-review.log');
+    const cleanupLogPath = path.join(repoRoot, '.omx', 'logs', 'agent-cleanup.log');
+    const reviewPid = spawnDetachedAgentProcess({
+      command: 'bash',
+      args: [reviewScriptPath, '--interval', String(options.reviewIntervalSeconds)],
+      cwd: repoRoot,
+      logPath: reviewLogPath,
+    });
+    const cleanupPid = spawnDetachedAgentProcess({
+      command: process.execPath,
+      args: [
+        path.resolve(__filename),
+        'cleanup',
+        '--target',
+        repoRoot,
+        '--watch',
+        '--interval',
+        String(options.cleanupIntervalSeconds),
+        '--idle-minutes',
+        String(options.idleMinutes),
+      ],
+      cwd: repoRoot,
+      logPath: cleanupLogPath,
+    });
+
+    writeAgentsState(repoRoot, {
+      schemaVersion: 1,
+      repoRoot,
+      startedAt: new Date().toISOString(),
+      review: {
+        pid: reviewPid,
+        intervalSeconds: options.reviewIntervalSeconds,
+        script: reviewScriptPath,
+        logPath: reviewLogPath,
+      },
+      cleanup: {
+        pid: cleanupPid,
+        intervalSeconds: options.cleanupIntervalSeconds,
+        idleMinutes: options.idleMinutes,
+        script: path.resolve(__filename),
+        logPath: cleanupLogPath,
+      },
+    });
+
+    console.log(
+      `[${TOOL_NAME}] Started repo agents in ${repoRoot} (review pid=${reviewPid}, cleanup pid=${cleanupPid}).`,
+    );
+    console.log(`[${TOOL_NAME}] Logs: ${reviewLogPath}, ${cleanupLogPath}`);
+    process.exitCode = 0;
+    return;
+  }
+
+  if (options.subcommand === 'stop') {
+    const existingState = readAgentsState(repoRoot);
+    if (!existingState) {
+      console.log(`[${TOOL_NAME}] Repo agents are not running for ${repoRoot}.`);
+      process.exitCode = 0;
+      return;
+    }
+
+    const reviewStop = stopAgentProcessByPid(existingState?.review?.pid, 'review-bot-watch.sh');
+    const cleanupStop = stopAgentProcessByPid(existingState?.cleanup?.pid, `${path.basename(__filename)} cleanup`);
+
+    if (fs.existsSync(statePath)) {
+      fs.unlinkSync(statePath);
+    }
+
+    console.log(
+      `[${TOOL_NAME}] Stopped repo agents in ${repoRoot} (review=${reviewStop.status}, cleanup=${cleanupStop.status}).`,
+    );
+    process.exitCode = 0;
+    return;
+  }
+
+  const existingState = readAgentsState(repoRoot);
+  if (!existingState) {
+    console.log(`[${TOOL_NAME}] Repo agents status: inactive (${repoRoot})`);
+    process.exitCode = 0;
+    return;
+  }
+
+  const reviewPid = Number.parseInt(String(existingState?.review?.pid || ''), 10);
+  const cleanupPid = Number.parseInt(String(existingState?.cleanup?.pid || ''), 10);
+  console.log(
+    `[${TOOL_NAME}] Repo agents status: review=${processAlive(reviewPid) ? 'running' : 'stopped'}(pid=${reviewPid || 0}), cleanup=${processAlive(cleanupPid) ? 'running' : 'stopped'}(pid=${cleanupPid || 0})`,
+  );
+  process.exitCode = 0;
+}
+
 function report(rawArgs) {
   const options = parseReportArgs(rawArgs);
   const subcommand = options.subcommand || 'help';
@@ -3802,6 +4211,13 @@ function setup(rawArgs) {
   if (scanResult.errors === 0 && scanResult.warnings === 0) {
     console.log(`[${TOOL_NAME}] ✅ Setup complete.`);
     console.log(`[${TOOL_NAME}] Copy AI setup prompt with: ${SHORT_TOOL_NAME} copy-prompt`);
+    console.log(
+      `[${TOOL_NAME}] OpenSpec core workflow: /opsx:propose -> /opsx:apply -> /opsx:archive`,
+    );
+    console.log(
+      `[${TOOL_NAME}] Optional expanded OpenSpec profile: openspec config profile <profile-name> && openspec update`,
+    );
+    console.log(`[${TOOL_NAME}] OpenSpec guide: docs/openspec-getting-started.md`);
   }
 
   setExitCodeFromScan(scanResult);
@@ -3895,15 +4311,42 @@ function cleanup(rawArgs) {
   if (!options.keepCleanWorktrees) {
     args.push('--only-dirty-worktrees');
   }
+  if (options.idleMinutes > 0) {
+    args.push('--idle-minutes', String(options.idleMinutes));
+  }
   args.push('--delete-branches');
   if (!options.keepRemote) {
     args.push('--delete-remote-branches');
   }
 
-  const runResult = run('bash', args, { cwd: repoRoot, stdio: 'inherit' });
-  if (runResult.status !== 0) {
-    throw new Error('Cleanup command failed');
+  const runCleanupCycle = () => {
+    const runResult = run('bash', args, { cwd: repoRoot, stdio: 'inherit' });
+    if (runResult.status !== 0) {
+      throw new Error('Cleanup command failed');
+    }
+  };
+
+  if (options.watch) {
+    let cycle = 0;
+    while (true) {
+      cycle += 1;
+      console.log(
+        `[${TOOL_NAME}] Cleanup watch cycle=${cycle} (interval=${options.intervalSeconds}s, idleMinutes=${options.idleMinutes}).`,
+      );
+      runCleanupCycle();
+      if (options.once) {
+        break;
+      }
+      const sleepResult = run('sleep', [String(options.intervalSeconds)], { cwd: repoRoot });
+      if (sleepResult.status !== 0) {
+        throw new Error(`Cleanup watch sleep failed (interval=${options.intervalSeconds}s)`);
+      }
+    }
+    process.exitCode = 0;
+    return;
   }
+
+  runCleanupCycle();
   process.exitCode = 0;
 }
 
@@ -4358,6 +4801,11 @@ function main() {
     return;
   }
 
+  if (command === 'agents') {
+    agents(rest);
+    return;
+  }
+
   if (command === 'finish') {
     finish(rest);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "5.0.9",
+  "version": "5.0.12",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,
@@ -29,7 +29,8 @@
     "agent:safety:scan": "gx scan",
     "agent:safety:fix": "gx fix",
     "agent:safety:doctor": "gx doctor",
-    "agent:review:watch": "bash ./scripts/review-bot-watch.sh"
+    "agent:review:watch": "bash ./scripts/review-bot-watch.sh",
+    "agent:finish": "gx finish --all"
   },
   "engines": {
     "node": ">=18"
@@ -53,12 +54,12 @@
   "author": "recodeecom",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/recodeecom/multiagent-safety.git"
+    "url": "git+https://github.com/recodeee/guardex.git"
   },
   "bugs": {
-    "url": "https://github.com/recodeecom/multiagent-safety/issues"
+    "url": "https://github.com/recodeee/guardex/issues"
   },
-  "homepage": "https://github.com/recodeecom/multiagent-safety#readme",
+  "homepage": "https://github.com/recodeee/guardex#readme",
   "funding": "https://github.com/sponsors/recodeecom",
   "publishConfig": {
     "access": "public"

package/templates/AGENTS.multiagent-safety.md

@@ -1,5 +1,5 @@
 <!-- multiagent-safety:START -->
-## Multi-Agent Execution Contract (multiagent-safety)
+## Multi-Agent Execution Contract (GX)
 
 0. Session plan comment + read gate (required)
 
@@ -13,12 +13,13 @@
 - In-place branch mode is disallowed: never switch the active local/base checkout to an agent branch.
 - Treat the base branch (`main` or the user's current local base branch) as read-only while the agent branch is active.
 - Agent completion defaults to `scripts/codex-agent.sh`, which auto-finishes the branch (auto-commit changed files, push/create PR, attempt merge, and pull the local base branch after merge).
+- OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR for those changes (via `codex-agent` or `agent-branch-finish`).
 - Auto-finish now waits for required checks/merge and then cleans merged sandbox branch/worktree by default.
 - Use `--no-cleanup` only when you explicitly need to keep a merged sandbox for audit/debug follow-up.
 - If codex-agent auto-finish cannot complete, immediately run `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr --wait-for-merge` and keep the branch open until checks/review pass.
 - If merge/rebase conflicts block auto-finish, run a conflict-resolution review pass in that sandbox branch, then rerun `agent-branch-finish.sh --via-pr` until merged.
 - Completion is not valid until these are true: commit exists on the agent branch, branch is pushed to `origin`, and PR/merge status is produced by `agent-branch-finish.sh` or `codex-agent`.
-- For every new task, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch; otherwise create a fresh one from the current local base snapshot with `scripts/agent-branch-start.sh`.
+- For every new task, including follow-up work in the same chat/session, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch; otherwise create a fresh one from the current local base snapshot with `scripts/agent-branch-start.sh`.
 - Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
 - If the change publishes or bumps a version, the same change must also update release notes/changelog entries.
 

package/templates/codex/skills/guardex/SKILL.md

@@ -38,4 +38,52 @@ gx scan
 - For one-command Codex sandbox startup, use `bash scripts/codex-agent.sh "<task>" "<agent-name>"`.
 - `scripts/codex-agent.sh` auto-syncs the sandbox branch against base before each task and auto-finishes merge/PR flow after Codex exits.
 - Auto-finish keeps the branch/worktree by default; remove merged branches explicitly with `gx cleanup` (or `gx cleanup --branch "<agent-branch>"`).
+- For skill-file-only merges into the local base branch (`dev` by default), use `$guardex-merge-skills-to-dev`.
 - Do not bypass protected branch safeguards unless explicitly required.
+
+## Bulk merge runbook (changed agent branches)
+
+Use this when a repo has many `agent/*` branches/worktrees with pending changes and you need them merged into the base branch quickly.
+
+1. Confirm base and guardrails are healthy:
+
+```sh
+git status --short --branch
+git pull --ff-only origin "$(git config --get multiagent.baseBranch || echo dev)"
+gx scan
+```
+
+2. Run bulk finish first:
+
+```sh
+gx finish --all
+```
+
+3. If a branch fails with `already used by worktree` or stale rebase hints, clear the stale state in that worktree, then retry targeted finish:
+
+```sh
+git -C "<worktree>" rebase --abort || true
+gx finish --branch "<agent-branch>" --base "$(git config --get multiagent.baseBranch || echo dev)" --no-wait-for-merge --cleanup
+```
+
+4. If `gh pr merge` exits non-zero due local branch deletion but PR is already merged, treat it as merged and verify with:
+
+```sh
+gh pr view "<pr-number>" --json state,mergedAt,url
+```
+
+5. If a branch is still ahead of base with no open PR, create and merge a follow-up PR manually:
+
+```sh
+gh pr create --base "<base-branch>" --head "<agent-branch>" --title "Auto-finish: <agent-branch>" --body "Follow-up merge for pending branch commits."
+gh pr merge "<pr-number>" --squash --delete-branch
+```
+
+6. Final verification:
+
+```sh
+gh pr list --state open --search "head:agent/ base:<base-branch>"
+git pull --ff-only origin "<base-branch>"
+gx cleanup
+gx scan
+```

package/templates/codex/skills/guardex-merge-skills-to-dev/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: guardex-merge-skills-to-dev
+description: "Use when you need to merge SKILL.md updates from agent branches/worktrees into the local base branch (default: dev) with the multiagent-safety flow."
+---
+
+# GuardeX Merge Skills to dev
+
+Use this skill when you only want to promote Codex skill file updates into the base branch (normally `dev`) without editing the visible base checkout directly.
+
+## What this merges
+
+- `.codex/skills/**/SKILL.md`
+- `templates/codex/skills/**/SKILL.md`
+
+## Merge runbook (safe path)
+
+1. Resolve the base branch:
+
+```sh
+BASE_BRANCH="$(git config --get multiagent.baseBranch || echo dev)"
+echo "$BASE_BRANCH"
+```
+
+2. Start a dedicated integration sandbox from base:
+
+```sh
+bash scripts/agent-branch-start.sh "merge-skill-files-to-${BASE_BRANCH}" "skill-merge" "$BASE_BRANCH"
+```
+
+3. Enter the sandbox worktree printed by the command above.
+
+4. Pull only skill files from each source agent branch:
+
+```sh
+SOURCE_BRANCH="<agent-branch>"
+git checkout "$SOURCE_BRANCH" -- ':(glob).codex/skills/**/SKILL.md' ':(glob)templates/codex/skills/**/SKILL.md'
+```
+
+5. Verify scope before commit:
+
+```sh
+git status --short
+git diff --name-only
+```
+
+6. Commit and merge back to base using guardex finish flow:
+
+```sh
+git add .codex/skills templates/codex/skills
+git commit -m "Merge skill file updates into ${BASE_BRANCH}"
+bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)" --base "$BASE_BRANCH" --via-pr --wait-for-merge --cleanup
+```
+
+## Notes
+
+- If a source branch has non-skill changes, this runbook keeps them out of the merge.
+- If merge conflicts occur, resolve only within the skill files, then rerun `agent-branch-finish.sh`.
+- Do not commit directly on `dev`/`main`; always merge through an agent branch/worktree.

package/templates/github/pull.yml.example

@@ -0,0 +1,6 @@
+version: "1"
+rules:
+  - base: main
+    upstream: upstream-owner:main
+    mergeMethod: hardreset
+    mergeUnstable: true

package/templates/github/workflows/cr.yml

@@ -0,0 +1,21 @@
+name: Code Review
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  review:
+    if: ${{ secrets.OPENAI_API_KEY != '' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: anc95/ChatGPT-CodeReview@main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_API_ENDPOINT: https://api.openai.com/v1
+          MODEL: gpt-4o-mini

package/templates/scripts/agent-branch-start.sh

@@ -193,6 +193,26 @@ hydrate_local_helper_in_worktree() {
   echo "[agent-branch-start] Hydrated local helper in worktree: ${relative_path}"
 }
 
+hydrate_dependency_dir_symlink_in_worktree() {
+  local repo="$1"
+  local worktree="$2"
+  local relative_path="$3"
+  local source_path="${repo}/${relative_path}"
+  local target_path="${worktree}/${relative_path}"
+
+  if [[ ! -d "$source_path" ]]; then
+    return 0
+  fi
+
+  if [[ -e "$target_path" ]]; then
+    return 0
+  fi
+
+  mkdir -p "$(dirname "$target_path")"
+  ln -s "$source_path" "$target_path"
+  echo "[agent-branch-start] Linked dependency dir in worktree: ${relative_path}"
+}
+
 initialize_openspec_plan_workspace() {
   local repo="$1"
   local worktree="$2"
@@ -341,6 +361,9 @@ if [[ -n "$auto_transfer_stash_ref" ]]; then
 fi
 
 hydrate_local_helper_in_worktree "$repo_root" "$worktree_path" "scripts/codex-agent.sh"
+hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "node_modules"
+hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/frontend/node_modules"
+hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/backend/node_modules"
 if ! initialize_openspec_plan_workspace "$repo_root" "$worktree_path" "$openspec_plan_slug"; then
   exit 1
 fi

package/templates/scripts/agent-worktree-prune.sh

@@ -9,6 +9,10 @@ DELETE_BRANCHES=0
 DELETE_REMOTE_BRANCHES=0
 ONLY_DIRTY_WORKTREES=0
 TARGET_BRANCH=""
+IDLE_MINUTES=0
+NOW_EPOCH_RAW="${MUSAFETY_PRUNE_NOW_EPOCH:-}"
+IDLE_SECONDS=0
+NOW_EPOCH=0
 
 if [[ -n "$BASE_BRANCH" ]]; then
   BASE_BRANCH_EXPLICIT=1
@@ -45,9 +49,13 @@ while [[ $# -gt 0 ]]; do
       TARGET_BRANCH="${2:-}"
       shift 2
       ;;
+    --idle-minutes)
+      IDLE_MINUTES="${2:-}"
+      shift 2
+      ;;
     *)
       echo "[agent-worktree-prune] Unknown argument: $1" >&2
-      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--only-dirty-worktrees] [--branch <agent/...>]" >&2
+      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--only-dirty-worktrees] [--branch <agent/...>] [--idle-minutes <minutes>]" >&2
       exit 1
       ;;
   esac
@@ -103,6 +111,16 @@ if [[ -n "$TARGET_BRANCH" && "$TARGET_BRANCH" != agent/* ]]; then
   exit 1
 fi
 
+if [[ ! "$IDLE_MINUTES" =~ ^[0-9]+$ ]]; then
+  echo "[agent-worktree-prune] --idle-minutes must be an integer >= 0." >&2
+  exit 1
+fi
+
+if [[ -n "$NOW_EPOCH_RAW" && ! "$NOW_EPOCH_RAW" =~ ^[0-9]+$ ]]; then
+  echo "[agent-worktree-prune] MUSAFETY_PRUNE_NOW_EPOCH must be a unix timestamp integer." >&2
+  exit 1
+fi
+
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
   BASE_BRANCH="$(resolve_base_branch)"
 fi
@@ -117,6 +135,13 @@ if ! git -C "$repo_root" show-ref --verify --quiet "refs/heads/${BASE_BRANCH}";
   exit 1
 fi
 
+IDLE_SECONDS=$((IDLE_MINUTES * 60))
+if [[ -n "$NOW_EPOCH_RAW" ]]; then
+  NOW_EPOCH="$NOW_EPOCH_RAW"
+else
+  NOW_EPOCH="$(date +%s)"
+fi
+
 run_cmd() {
   if [[ "$DRY_RUN" -eq 1 ]]; then
     echo "[agent-worktree-prune] [dry-run] $*"
@@ -167,6 +192,71 @@ select_unique_worktree_path() {
   printf '%s' "$candidate"
 }
 
+read_branch_activity_epoch() {
+  local branch="$1"
+  local wt="${2:-}"
+  local activity_epoch=""
+
+  activity_epoch="$(
+    git -C "$repo_root" reflog show --format='%ct' -n 1 "refs/heads/${branch}" 2>/dev/null \
+      | head -n 1 \
+      | tr -d '[:space:]'
+  )"
+  if [[ -z "$activity_epoch" ]]; then
+    activity_epoch="$(
+      git -C "$repo_root" log -1 --format='%ct' "$branch" 2>/dev/null \
+        | head -n 1 \
+        | tr -d '[:space:]'
+    )"
+  fi
+
+  if [[ -n "$wt" && -d "$wt" ]]; then
+    local lock_file="${wt}/.omx/state/agent-file-locks.json"
+    if [[ -f "$lock_file" ]]; then
+      local lock_mtime=""
+      lock_mtime="$(stat -c %Y "$lock_file" 2>/dev/null || stat -f %m "$lock_file" 2>/dev/null || true)"
+      if [[ "$lock_mtime" =~ ^[0-9]+$ ]]; then
+        if [[ -z "$activity_epoch" || "$lock_mtime" -gt "$activity_epoch" ]]; then
+          activity_epoch="$lock_mtime"
+        fi
+      fi
+    fi
+  fi
+
+  printf '%s' "$activity_epoch"
+}
+
+skipped_recent=0
+
+branch_idle_gate() {
+  local branch="$1"
+  local wt="$2"
+  local reason="$3"
+  if [[ "$IDLE_SECONDS" -le 0 ]]; then
+    return 0
+  fi
+  if [[ -z "$branch" ]]; then
+    return 0
+  fi
+
+  local last_activity_epoch=""
+  last_activity_epoch="$(read_branch_activity_epoch "$branch" "$wt")"
+  if [[ ! "$last_activity_epoch" =~ ^[0-9]+$ ]]; then
+    return 0
+  fi
+
+  local idle_age=$((NOW_EPOCH - last_activity_epoch))
+  if [[ "$idle_age" -lt 0 ]]; then
+    idle_age=0
+  fi
+  if [[ "$idle_age" -lt "$IDLE_SECONDS" ]]; then
+    skipped_recent=$((skipped_recent + 1))
+    echo "[agent-worktree-prune] Skipping recent branch (${reason}): ${branch} (idle=${idle_age}s < ${IDLE_SECONDS}s)"
+    return 1
+  fi
+  return 0
+}
+
 relocated_foreign=0
 skipped_foreign=0
 
@@ -273,6 +363,10 @@ process_entry() {
     return
   fi
 
+  if ! branch_idle_gate "$branch" "$wt" "$remove_reason"; then
+    return
+  fi
+
   if [[ "$FORCE_DIRTY" -ne 1 ]] && ! is_clean_worktree "$wt"; then
     skipped_dirty=$((skipped_dirty + 1))
     echo "[agent-worktree-prune] Skipping dirty worktree (${remove_reason}): ${wt}"
@@ -339,6 +433,9 @@ if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
     if branch_has_worktree "$branch"; then
       continue
     fi
+    if ! branch_idle_gate "$branch" "" "stale-merged-branch"; then
+      continue
+    fi
     if git -C "$repo_root" merge-base --is-ancestor "$branch" "$BASE_BRANCH"; then
       if run_cmd git -C "$repo_root" branch -d "$branch" >/dev/null 2>&1; then
         removed_branches=$((removed_branches + 1))
@@ -356,7 +453,7 @@ fi
 
 run_cmd git -C "$repo_root" worktree prune
 
-echo "[agent-worktree-prune] Summary: base=${BASE_BRANCH}, removed_worktrees=${removed_worktrees}, removed_branches=${removed_branches}, skipped_active=${skipped_active}, skipped_dirty=${skipped_dirty}"
+echo "[agent-worktree-prune] Summary: base=${BASE_BRANCH}, idle_minutes=${IDLE_MINUTES}, removed_worktrees=${removed_worktrees}, removed_branches=${removed_branches}, skipped_active=${skipped_active}, skipped_dirty=${skipped_dirty}, skipped_recent=${skipped_recent}"
 if [[ "$relocated_foreign" -gt 0 || "$skipped_foreign" -gt 0 ]]; then
   echo "[agent-worktree-prune] Foreign routing: relocated=${relocated_foreign}, skipped=${skipped_foreign}"
 fi
@@ -366,3 +463,6 @@ fi
 if [[ "$skipped_dirty" -gt 0 ]]; then
   echo "[agent-worktree-prune] Tip: dirty worktrees were preserved. Clean/finish them first, or pass --force-dirty to remove anyway." >&2
 fi
+if [[ "$IDLE_SECONDS" -gt 0 && "$skipped_recent" -gt 0 ]]; then
+  echo "[agent-worktree-prune] Tip: recent branches were preserved by --idle-minutes=${IDLE_MINUTES}. Re-run later or lower the threshold." >&2
+fi