@imdeadpool/guardex 5.0.9 → 5.0.11

package/README.md

@@ -124,12 +124,21 @@ 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
@@ -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`.
@@ -247,6 +287,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 +328,16 @@ npm pack --dry-run
 
 ## Release notes
 
+### 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

@@ -78,6 +78,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';
@@ -128,6 +129,7 @@ const SUGGESTIBLE_COMMANDS = [
   'init',
   'doctor',
   'review',
+  'agents',
   'finish',
   'report',
   'copy-prompt',
@@ -154,7 +156,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 +168,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,17 +207,28 @@ 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
 `;
 
@@ -229,6 +244,8 @@ 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
@@ -1567,6 +1584,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 +2356,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 +2407,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 +3607,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 +3749,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 +4184,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 +4284,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 +4774,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.11",
   "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"

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

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