@imdeadpool/guardex 7.0.38 → 7.0.41

package/README.md

@@ -9,7 +9,6 @@
   and human teammates working the same codebase at the same time.
 </p>
 
-Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman. See [about_description.txt](./about_description.txt).
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@imdeadpool/guardex"><img alt="npm version" src="https://img.shields.io/npm/v/%40imdeadpool%2Fguardex?label=npm&style=flat-square&color=cb3837&logo=npm&logoColor=white"></a>
@@ -157,7 +156,7 @@ $ gx
   ● oh-my-codex                    active
   ● oh-my-claude-sisyphus          active
   ● @fission-ai/openspec           active
-  ● cavemem                        active
+  ● colony                         active
   ● cavekit                        optional · not installed
   ● gh                             authenticated
 
@@ -266,6 +265,27 @@ Being honest about where this still has issues:
 <details open>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.41
+- Bumped `@imdeadpool/guardex` from `7.0.40` to `7.0.41` so the current
+  `main` payload can publish under a fresh npm version after the `v7.0.40`
+  GitHub release landed without a matching npm registry package.
+- Ships the Colony companion setup as the default global companion surface:
+  `colony` maps to `@imdeadpool/colony-cli`, README setup documents
+  `colony install --ide ...`, and status tests/images expect Colony instead
+  of cavemem.
+
+### v7.0.40
+- Bumped `@imdeadpool/guardex` from `7.0.39` to `7.0.40` so the current
+  `main` payload can publish under a fresh npm version after `7.0.39` reached
+  the registry.
+- No new CLI command behavior is introduced in this release lane.
+
+### v7.0.39
+- Bumped `@imdeadpool/guardex` from `7.0.38` to `7.0.39` so the current
+  `main` payload can publish under a fresh npm version after `7.0.38` reached
+  the registry.
+- No new CLI command behavior is introduced in this release lane.
+
 ### v7.0.38
 - Bumped `@imdeadpool/guardex` from `7.0.37` to `7.0.38` so the current
   `main` payload can publish under a fresh npm version after `7.0.37` reached
@@ -309,7 +329,7 @@ Install repo skills with `npx skills add recodee/gitguardex`; `npx skills add re
 | [**oh-my-codex**](https://github.com/Yeachan-Heo/oh-my-codex) — `npm i -g oh-my-codex` | Codex config + skills framework. Merged into every agent worktree so each spawned Codex starts with the same tuned config. | [![stars](https://img.shields.io/github/stars/Yeachan-Heo/oh-my-codex?style=social)](https://github.com/Yeachan-Heo/oh-my-codex) |
 | [**oh-my-claudecode**](https://github.com/Yeachan-Heo/oh-my-claudecode) — `npm i -g oh-my-claude-sisyphus@latest` | Claude-side mirror of oh-my-codex. Skills, commands, and defaults for every Claude Code session. | [![stars](https://img.shields.io/github/stars/Yeachan-Heo/oh-my-claudecode?style=social)](https://github.com/Yeachan-Heo/oh-my-claudecode) |
 | [**OpenSpec**](https://github.com/Fission-AI/OpenSpec) — `npm i -g @fission-ai/openspec` | Structured plan / change / apply / archive flow so long agent runs don't drift off-task. | [![stars](https://img.shields.io/github/stars/Fission-AI/OpenSpec?style=social)](https://github.com/Fission-AI/OpenSpec) |
-| [**cavemem**](https://github.com/JuliusBrussee/cavemem) — `npm i -g cavemem` | Local persistent memory for agents via SQLite + MCP. Retains compressed history across runs. | [![stars](https://img.shields.io/github/stars/JuliusBrussee/cavemem?style=social)](https://github.com/JuliusBrussee/cavemem) |
+| [**Colony**](https://github.com/recodeee/colony) — `npm i -g @imdeadpool/colony-cli` | Multi-agent task coordination and handoff routing. After install, register runtimes with `colony install --ide codex`, `colony install --ide claude-code`, `colony install --ide cursor`, `colony install --ide gemini-cli`, or `colony install --ide opencode`, then verify with `colony status`. | [![stars](https://img.shields.io/github/stars/recodeee/colony?style=social)](https://github.com/recodeee/colony) |
 | [**cavekit**](https://github.com/JuliusBrussee/cavekit) — `npx skills add JuliusBrussee/cavekit` | Spec-driven build loop with `spec`, `build`, `check`, `caveman`, `backprop` skills bundled in. | [![stars](https://img.shields.io/github/stars/JuliusBrussee/cavekit?style=social)](https://github.com/JuliusBrussee/cavekit) |
 | [**caveman**](https://github.com/JuliusBrussee/caveman) — `npx skills add JuliusBrussee/caveman` | Ultra-compressed response mode for Claude / Codex. Less output-token churn on long reviews and debug loops. | [![stars](https://img.shields.io/github/stars/JuliusBrussee/caveman?style=social)](https://github.com/JuliusBrussee/caveman) |
 | [**codex-account-switcher**](https://github.com/recodeecom/codex-account-switcher-cli) — `npm i -g @imdeadpool/codex-account-switcher` | Multi-identity Codex account switcher. Auto-registers accounts on `codex login`; switch with one command. | [![stars](https://img.shields.io/github/stars/recodeecom/codex-account-switcher-cli?style=social)](https://github.com/recodeecom/codex-account-switcher-cli) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.38",
+  "version": "7.0.41",
   "description": "Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.",
   "license": "MIT",
   "preferGlobal": true,

package/src/cli/main.js

@@ -408,8 +408,9 @@ function runSetupBootstrapInternal(options) {
 }
 
 function extractAgentBranchStartMetadata(output) {
-  const branchMatch = String(output || '').match(/^\[agent-branch-start\] Created branch: (.+)$/m);
-  const worktreeMatch = String(output || '').match(/^\[agent-branch-start\] Worktree: (.+)$/m);
+  const outputText = String(output || '');
+  const branchMatch = outputText.match(/^\[agent-branch-start\] (?:Created branch|Reusing existing branch): (.+)$/m);
+  const worktreeMatch = outputText.match(/^\[agent-branch-start\] Worktree: (.+)$/m);
   return {
     branch: branchMatch ? branchMatch[1].trim() : '',
     worktreePath: worktreeMatch ? worktreeMatch[1].trim() : '',
@@ -3466,7 +3467,7 @@ function pivot(rawArgs) {
   }
   const stdoutText = String(result.stdout || '');
   const wtMatch = stdoutText.match(/^\[agent-branch-start\] Worktree:\s+(.+)$/m);
-  const branchMatch = stdoutText.match(/^\[agent-branch-start\] Created branch:\s+(.+)$/m);
+  const branchMatch = stdoutText.match(/^\[agent-branch-start\] (?:Created branch|Reusing existing branch):\s+(.+)$/m);
   if (wtMatch) {
     const wtPath = wtMatch[1].trim();
     process.stdout.write('\n');

package/src/context.js

@@ -21,7 +21,7 @@ const GLOBAL_INSTALL_COMMAND = `npm i -g ${packageJson.name}`;
 const OPENSPEC_PACKAGE = '@fission-ai/openspec';
 const OMC_PACKAGE = 'oh-my-claude-sisyphus';
 const OMC_REPO_URL = 'https://github.com/Yeachan-Heo/oh-my-claudecode';
-const CAVEMEM_PACKAGE = 'cavemem';
+const COLONY_PACKAGE = '@imdeadpool/colony-cli';
 const NPX_BIN = process.env.GUARDEX_NPX_BIN || 'npx';
 const GUARDEX_HOME_DIR = path.resolve(process.env.GUARDEX_HOME_DIR || os.homedir());
 const GLOBAL_TOOLCHAIN_SERVICES = [
@@ -32,7 +32,7 @@ const GLOBAL_TOOLCHAIN_SERVICES = [
     dependencyUrl: OMC_REPO_URL,
   },
   { name: OPENSPEC_PACKAGE, packageName: OPENSPEC_PACKAGE },
-  { name: CAVEMEM_PACKAGE, packageName: CAVEMEM_PACKAGE },
+  { name: 'colony', packageName: COLONY_PACKAGE },
   {
     name: '@imdeadpool/codex-account-switcher',
     packageName: '@imdeadpool/codex-account-switcher',
@@ -674,7 +674,7 @@ module.exports = {
   OPENSPEC_PACKAGE,
   OMC_PACKAGE,
   OMC_REPO_URL,
-  CAVEMEM_PACKAGE,
+  COLONY_PACKAGE,
   NPX_BIN,
   GUARDEX_HOME_DIR,
   GLOBAL_TOOLCHAIN_SERVICES,

package/src/doctor/index.js

@@ -310,7 +310,7 @@ function extractAgentBranchFinishPrUrl(output) {
 function doctorFinishFlowIsPending(output) {
   return (
     /\[agent-branch-finish\] PR merge not completed yet; leaving PR open\./.test(output) ||
-    /\[agent-branch-finish\] Merge pending review\/check policy\. Branch cleanup skipped for now\./.test(output) ||
+    /\[agent-branch-finish\] PR pending review\/check policy\./.test(output) ||
     /\[agent-branch-finish\] PR auto-merge enabled; waiting for required checks\/reviews\./.test(output)
   );
 }

package/src/sandbox/index.js

@@ -65,8 +65,9 @@ function assertProtectedMainWriteAllowed(options, commandName) {
 }
 
 function extractAgentBranchStartMetadata(output) {
-  const branchMatch = String(output || '').match(/^\[agent-branch-start\] Created branch: (.+)$/m);
-  const worktreeMatch = String(output || '').match(/^\[agent-branch-start\] Worktree: (.+)$/m);
+  const outputText = String(output || '');
+  const branchMatch = outputText.match(/^\[agent-branch-start\] (?:Created branch|Reusing existing branch): (.+)$/m);
+  const worktreeMatch = outputText.match(/^\[agent-branch-start\] Worktree: (.+)$/m);
   return {
     branch: branchMatch ? branchMatch[1].trim() : '',
     worktreePath: worktreeMatch ? worktreeMatch[1].trim() : '',

package/templates/AGENTS.multiagent-safety.md

@@ -1,63 +1,421 @@
 <!-- multiagent-safety:START -->
-## Multi-Agent Execution Contract (GX)
+## Multi-Agent Execution Contract: Guardex + Colony
 
-**Repo toggle.** Guardex is enabled by default. If the repo root `.env` sets `GUARDEX_ON=0`, `false`, `no`, or `off`, treat this entire Guardex contract as disabled for the repo and do not require Guardex worktrees, lock claims, completion flow, or OpenSpec workflow until `GUARDEX_ON` is re-enabled.
+### Repo toggle
 
-**Repo toggle examples.** Add one of these lines to the repo-root `.env` file:
-`GUARDEX_ON=0` disables Guardex for that repo.
-`GUARDEX_ON=1` explicitly enables Guardex for that repo again.
+Guardex is enabled by default.
 
-**Task-size routing.** Small tasks stay in direct caveman-only mode. For typos, single-file tweaks, one-liners, version bumps, or similarly bounded asks, solve directly and do not escalate into heavy OMX orchestration just because a keyword appears. Treat `quick:`, `simple:`, `tiny:`, `minor:`, `small:`, `just:`, and `only:` as explicit lightweight escape hatches.
-Promote to OMX orchestration only when the task is medium/large: multi-file behavior changes, API/schema work, refactors, migrations, architecture, cross-cutting scope, or long prompts. Heavy OMX modes (`ralph`, `autopilot`, `team`, `ultrawork`, `swarm`, `ralplan`) are for that larger scope. If the task grows while working, upgrade then.
+If the repo-root `.env` sets any of these values, treat this entire Guardex contract as disabled for the repo:
 
-## Token / Context Budget
+```text
+GUARDEX_ON=0
+GUARDEX_ON=false
+GUARDEX_ON=no
+GUARDEX_ON=off
+```
+
+When disabled, do not require Guardex worktrees, lock claims, completion flow, or OpenSpec workflow until `GUARDEX_ON` is re-enabled.
+
+To explicitly enable:
+
+```text
+GUARDEX_ON=1
+```
+
+### Core rules
+
+- Work from an `agent/*` branch and worktree, never directly on the protected base branch.
+- Claim files before edits.
+- Use Colony for coordination before falling back to OMX state/notepad.
+- Use OpenSpec for durable behavior contracts and change-driven work.
+- Keep outputs compact: less word, same proof.
+- Commit, push, and open/update a PR for completed work unless the user explicitly says to keep it local.
+- Do not embed stale memory dumps, generated status snapshots, PR transcripts, session history, or long logs in this file.
+
+### Task-size routing
+
+Small tasks stay direct and caveman-only.
+
+For typos, single-file tweaks, one-liners, version bumps, comment-only changes, or similarly bounded asks, solve directly and do not escalate into heavy orchestration just because a keyword appears.
+
+Treat these prefixes as explicit lightweight escape hatches:
+
+- `quick:`
+- `simple:`
+- `tiny:`
+- `minor:`
+- `small:`
+- `just:`
+- `only:`
+
+Promote to full Guardex / OMX orchestration only when scope grows into:
+
+- multi-file behavior change
+- API/schema work
+- refactor
+- migration
+- architecture
+- cross-cutting scope
+- long prompt
+- multi-agent execution
+
+### Colony coordination loop
+
+Use Colony as the primary coordination surface.
+
+On every startup, resume, follow-up, or "continue" request, run this order:
+
+1. `mcp__colony__hivemind_context`
+2. `mcp__colony__attention_inbox`
+3. `mcp__colony__task_ready_for_agent`
+4. `mcp__colony__search` only when prior decisions, earlier lanes, file history, or error context matter.
+
+Rules:
+
+- Use `task_ready_for_agent` to choose work.
+- Use `task_list` only for browsing/debugging. Do not use `task_list` as the normal work picker.
+- If an agent reaches for `task_list` repeatedly while choosing work, stop and call `task_ready_for_agent` instead. `task_list` is an inventory tool, not a scheduler.
+- Before editing files on an active task, call `task_claim_file` for each touched file.
+- Use `task_post` for task-thread notes, decisions, blockers, and working-state updates.
+- Use `task_message` / `task_messages` for directed agent-to-agent communication.
+- Use `get_observations` only after compact Colony tools return IDs worth hydrating.
+
+Fallback:
+
+- Colony is considered unavailable only when the MCP namespace is missing, the tool call fails, or the installed Colony server does not expose the required tool.
+- If `attention_inbox` or `task_ready_for_agent` is missing, fall back to `hivemind_context`, then `task_list`, then hydrate only the relevant task IDs.
+- Do not skip Colony just because OMX state exists. OMX is fallback, not the first coordination source.
+- Read `.omx/state` and `.omx/notepad.md` only when Colony is unavailable, missing the needed state, or the task explicitly depends on legacy OMX state.
+- Keep `.omx/notepad.md` lean: live handoffs only.
+
+### Working-state notes
+
+Colony is preferred over generic notepad state.
+
+A working-state note should be task-scoped, searchable, and useful to another agent resuming the lane.
+
+When saving progress, use a task-scoped Colony note when possible:
+
+```text
+task_post kind=note
+content="branch=<branch>; task=<task>; blocker=<blocker>; next=<next>; evidence=<path|command|PR|spec>"
+```
+
+Use exactly these fields for handoff-style notes:
+
+- `branch`
+- `task`
+- `blocker`
+- `next`
+- `evidence`
+
+Do not store long proof dumps, stale narrative, or full logs in notepads. Put bulky proof in OpenSpec artifacts, PRs, or command output.
+
+### Token / context budget
 
 Default: less word, same proof.
 
-- For prompts about `token inefficiency`, `reviewer mode`, `minimal token overhead`, or session waste patterns, switch into low-overhead mode: plan in at most 4 bullets, execute by phase, batch related reads/commands, avoid duplicate reads and interactive loops, keep outputs compact, and verify once per phase.
-- Low output alone is not a defect. A bounded run that finishes in roughly <=10 steps is usually fine; low output spread across 20+ steps with rising per-turn input is fragmentation and should be treated as context growth first.
-- Startup / resume summaries stay tiny: `branch`, `task`, `blocker`, `next step`, and `evidence`.
-- Memory-driven starts stay ordered: read active `.omx/state` first, then one live `.omx/notepad.md` handoff, then external memory only when the task depends on prior repo decisions, a previous lane, or ambiguous continuity. Stop after the first 1-2 relevant hits.
-- Front-load scaffold/path discovery into one grouped inspection pass. Avoid serial `ls` / `find` / `rg` / `cat` retries that only rediscover the same path state.
-- Treat repeated `write_stdin`, repeated `sed` / `cat` peeks, and tiny diagnostic follow-up checks as strong negative signals. If they appear alongside climbing input cost, stop the probe loop and batch the next phase.
+- For prompts about `token inefficiency`, `reviewer mode`, `minimal token overhead`, or session waste patterns, switch into low-overhead mode.
+- Plan in at most 4 bullets.
+- Execute by phase.
+- Batch related reads and commands.
+- Avoid duplicate reads and interactive loops.
+- Keep outputs compact.
+- Verify once per phase.
+- Low output alone is not a defect. A bounded run that finishes in roughly <=10 steps is usually fine.
+- Low output spread across 20+ steps with rising per-turn input is fragmentation and should be treated as context growth first.
+- Startup / resume summaries stay tiny: `branch`, `task`, `blocker`, `next`, and `evidence`.
+- Front-load scaffold/path discovery into one grouped inspection pass. Avoid serial `ls` / `find` / `rg` / `cat` retries that rediscover the same path state.
+- Treat repeated `write_stdin`, repeated `sed` / `cat` peeks, and tiny diagnostic follow-up checks as strong negative signals.
+- If a session turns fragmented, collapse back to inspect once, patch once, verify once, and summarize once.
 - Tool / hook summaries stay tiny: command, status, last meaningful lines only. Drop routine hook boilerplate.
 - Keep raw terminal interaction out of long-lived context. For `write_stdin` or interactive babysitting, retain only process, action sent, current result, and next action.
 - Keep execution log separate from reasoning context: full commands/stdout belong in logs, while prompt context keeps only the latest 1-2 checkpoints plus the newest tool-result summary.
-- Treat local edit/commit, remote publish/PR, CI diagnosis, and cleanup as bounded phases. Do not spend fresh narration or approval turns on obvious safe follow-ons inside an already authorized phase unless the risk changes.
-- When a session turns fragmented, collapse back to inspect once, patch once, verify once, and summarize once.
-- Use a fixed checkpoint shape when compacting: `Task`, `Done`, `Current status`, and `Next`.
-- Keep `.omx/notepad.md` lean: live handoffs only. Use exactly `branch`, `task`, `blocker`, `next step`, and `evidence`; move narrative proof into OpenSpec artifacts, PRs, or command output.
+- Treat local edit/commit, remote publish/PR, CI diagnosis, and cleanup as bounded phases.
+- Do not spend fresh narration or approval turns on obvious safe follow-ons inside an already authorized phase unless the risk changes.
+
+### Caveman style
+
+Commentary and progress updates use smart-caveman `ultra` by default:
+
+- Answer order stays fixed: answer first, cause next, fix or next step last.
+- drop filler
+- use fragments when clear
+- answer first
+- cause next
+- fix or next step last
+
+Keep exact literals unchanged:
+
+- code
+- commands
+- file paths
+- flags
+- env vars
+- URLs
+- numbers
+- timestamps
+- error text
+
+Switch back to `lite` or normal wording for:
 
-## OMX Caveman Style
+- security warnings
+- irreversible actions
+- privacy/compliance notes
+- ordered instructions where fragments may confuse
+- confused users
+- commits
+- PR text
+- specs
+- logs
+- blocker evidence
 
-- Commentary and progress updates use smart-caveman `ultra` by default: drop articles, filler, pleasantries, and hedging. Fragments are fine when they stay clear.
-- Answer order stays fixed: answer first, cause next, fix or next step last. If yes/no fits, say yes/no first.
-- Keep literals exact: code, commands, file paths, flags, env vars, URLs, numbers, timestamps, and error text are never caveman-compressed.
-- Auto-clarity wins: switch back to `lite` or normal wording for security warnings, irreversible actions, privacy/compliance notes, ordered instructions where fragments may confuse, or when the user is confused and needs more detail.
-- Boundaries stay normal/exact for code, commits, PR text, specs, logs, and blocker evidence.
+Never caveman-compress commands, file paths, specs, logs, or blocker evidence.
+
+### Isolation
+
+Every task runs on a dedicated `agent/*` branch and worktree.
+
+Start with:
+
+```bash
+gx branch start "<task>" "<agent-name>"
+```
+
+Treat the base branch (`main` / `dev`) as read-only while an agent branch is active.
 
-**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions and auto-stashes a dirty tree before reverting - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
 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 instead of creating a fresh lane unless the user explicitly redirects scope.
-Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
 
-**Primary-tree lock (blocking).** On the primary checkout, do NOT run any of: `git checkout <ref>`, `git switch <ref>`, `git switch -c ...`, `git checkout -b ...`, or `git worktree add <path> <existing-agent-branch>`. The only branch-changing commands allowed on primary are `git fetch` and `git pull --ff-only` against the protected branch itself. To work on any `agent/*` branch, run `gx branch start ...` first, then `cd` into the printed `.omc/agent-worktrees/...` path and run every subsequent git command from inside that worktree. If you find yourself typing `git checkout agent/...` or `git switch agent/...` from the primary cwd, stop - that is the mistake that flips primary onto an agent branch.
+Never implement directly on the local/base branch checkout. Keep it unchanged and perform all edits in the agent sub-branch/worktree.
+
+### Primary-tree lock
+
+On the primary checkout, do not run:
+
+```bash
+git checkout <ref>
+git switch <ref>
+git switch -c ...
+git checkout -b ...
+git worktree add <path> <existing-agent-branch>
+```
+
+Allowed on primary:
+
+```bash
+git fetch
+git pull --ff-only
+```
+
+To work on any `agent/*` branch, run `gx branch start ...` first, then `cd` into the printed worktree path and run every subsequent git command from inside that worktree.
+
+If you are about to type `git checkout agent/...` or `git switch agent/...` from the primary checkout, stop. That is the mistake that flips primary onto an agent branch.
+
+### Dirty-tree rule
+
+Finish or stash edits inside the worktree they belong to before any branch switch on primary.
+
+The post-checkout guard may auto-stash a dirty primary tree as:
+
+```text
+guardex-auto-revert <ts> <prev>-><new>
+```
+
+That is a safety net, not a workflow. Do not rely on it routinely.
+
+Recover stashed changes with:
+
+```bash
+git stash list | grep 'guardex-auto-revert'
+```
+
+### Ownership
 
-**Dirty-tree rule.** Finish or stash edits inside the worktree they belong to before any branch switch on primary. The post-checkout guard auto-stashes a dirty primary tree as `guardex-auto-revert <ts> <prev>-><new>` before reverting, but that is a safety net, not a workflow; do not rely on it routinely. Recover stashed changes with `git stash list | grep 'guardex-auto-revert'`.
+Before editing, claim files.
 
-**Ownership.** Before editing, claim files: `gx locks claim --branch "<agent-branch>" <file...>`. Before deleting, confirm the path is in your claim. Don't edit outside your scope unless reassigned.
+Preferred Colony path when on an active task:
 
-**Handoff gate.** Post a one-line handoff note (plan/change, owned scope, intended action) before editing. Re-read the latest handoffs before replacing others' code.
+```text
+mcp__colony__task_claim_file
+```
+
+Guardex lock path:
+
+```bash
+gx locks claim --branch "<agent-branch>" <file...>
+```
+
+Before deleting, confirm the path is in your claim.
+
+Do not edit outside your scope unless reassigned.
+
+If another agent owns or recently touched nearby code:
+
+1. read latest Colony context
+2. post a handoff or question
+3. avoid reverting unrelated changes
+4. report conflicts instead of overwriting
+
+### Handoff gate
+
+Before editing, post a one-line handoff note through Colony `task_post` when a task is active.
+
+Use `.omx/notepad.md` only when Colony is unavailable or the lane explicitly depends on legacy OMX state.
+
+Handoff shape:
+
+```text
+branch=<branch>; task=<task>; blocker=<blocker>; next=<next>; evidence=<path|command|PR|spec>
+```
+
+Re-read latest Colony context before replacing another agent's code.
+
+### Completion
+
+Finish with:
+
+```bash
+gx branch finish --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup
+```
+
+or:
+
+```bash
+gx finish --all
+```
+
+Task is complete only when:
+
+1. changes are committed
+2. branch is pushed
+3. PR URL is recorded
+4. PR state is `MERGED`
+5. sandbox worktree is pruned
+6. final handoff records proof
+
+If anything blocks, append a `BLOCKED:` note and stop. Do not half-finish.
 
-**Completion.** Finish with `gx branch finish --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`). Task is only complete when: commit pushed, PR URL recorded, state = `MERGED`, sandbox worktree pruned. If anything blocks, append a `BLOCKED:` note and stop - don't half-finish.
 OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR before considering the branch complete.
 
-**Parallel safety.** Assume other agents edit nearby. Never revert unrelated changes. Report conflicts in the handoff.
+### Parallel safety
+
+Assume other agents edit nearby.
+
+- Never revert unrelated changes.
+- Never simplify or delete critical shared paths without explicit request and regression coverage.
+- Report conflicts in the handoff.
+- Prefer compatibility-preserving changes over endpoint-specific rewrites when other agents may be changing adjacent systems.
+
+### Reporting
+
+Every completion handoff includes:
+
+```text
+branch
+task
+files changed
+behavior touched
+verification commands/results
+PR URL
+merge state
+sandbox cleanup state
+risks/follow-ups
+```
+
+If blocked, use:
+
+```text
+BLOCKED:
+branch=<branch>
+task=<task>
+blocker=<blocker>
+next=<next>
+evidence=<path|command|PR|spec>
+```
+
+### Open questions
+
+If Codex/Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it in:
+
+```text
+openspec/plan/<plan-slug>/open-questions.md
+```
+
+as an unchecked item:
+
+```md
+- [ ] Question or blocker...
+```
+
+Resolve it in-place when answered instead of burying it in chat-only notes.
+
+### OpenSpec
+
+OpenSpec is the source of truth for change-driven repo work.
+
+For change-driven tasks, keep:
+
+```text
+openspec/changes/<slug>/tasks.md
+```
+
+current during work, not batched at the end.
+
+Task scaffolds and manual task edits must include a final completion/cleanup section that ends with PR merge + sandbox cleanup and records PR URL + final `MERGED` evidence.
+
+Validate specs before archive:
+
+```bash
+openspec validate --specs
+```
+
+Never archive unverified work.
+
+For `T0` / small `T1` lanes, use the compact Colony spec path when available. One Colony handoff plus `colony-spec.md` is enough. Do not create proposal/spec/tasks unless the task grows.
+
+For `T2` / `T3` lanes, keep proposal, spec, design, and tasks live while implementing.
+
+### Version bumps
+
+If a change bumps a published version, the same PR records release notes in the appropriate OpenSpec artifact or release-note mechanism for the repo.
+
+Do not edit `CHANGELOG.md` directly unless the repo explicitly requires manual changelog edits.
+
+### Verification gates
+
+Before claiming completion, run the narrowest meaningful verification for the touched area.
+
+Examples:
+
+```bash
+pnpm test
+pnpm typecheck
+pnpm lint
+```
+
+If a command cannot run, record:
+
+```text
+command
+reason it could not run
+risk
+next
+```
+
+Do not claim green verification without command output evidence.
+
+### What not to put in this file
 
-**Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
+Do not embed:
 
-**Open questions.** If Codex/Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it in `openspec/plan/<plan-slug>/open-questions.md` as an unchecked `- [ ]` item. Resolve it in-place when answered instead of burying it in chat-only notes.
+- stale memory dumps
+- PR transcripts
+- long logs
+- generated status snapshots
+- session history
+- full OpenSpec examples
+- repeated copies of long workflow docs
 
-**OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `gx branch finish ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
+Keep this section as the hard multi-agent contract. Put long examples and recovery docs in repo-specific workflow docs.
 
-**Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.
 <!-- multiagent-safety:END -->

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

@@ -508,7 +508,7 @@ is_local_branch_delete_error() {
 
 is_remote_branch_missing_error() {
   local output="$1"
-  if [[ "$output" == *"remote ref does not exist"* ]] || [[ "$output" == *"failed to push some refs"* ]]; then
+  if [[ "$output" == *"remote ref does not exist"* ]]; then
     return 0
   fi
   return 1
@@ -831,7 +831,7 @@ if [[ "$PUSH_ENABLED" -eq 1 ]]; then
           echo "[agent-branch-finish] Merge did not complete within wait window; keeping branch open." >&2
           exit 1
         fi
-        echo "[agent-branch-finish] Merge pending review/check policy. Branch cleanup skipped for now." >&2
+        echo "[agent-branch-finish] PR pending review/check policy. Worktree retained for now; the autofinish watcher (or 'gx worktree prune --include-pr-merged --delete-branches') will prune it after merge. Verify with 'git worktree list' before claiming the worktree is still on disk." >&2
         exit 0
       fi
       echo "[agent-branch-finish] PR flow failed." >&2
@@ -893,8 +893,8 @@ if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
         if is_remote_branch_missing_error "$remote_delete_output"; then
           echo "[agent-branch-finish] Remote branch '${SOURCE_BRANCH}' was already deleted; continuing cleanup." >&2
         else
+          echo "[agent-branch-finish] Warning: remote branch cleanup failed for '${SOURCE_BRANCH}' after merge; continuing local cleanup." >&2
           echo "$remote_delete_output" >&2
-          exit 1
         fi
       fi
     fi

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

@@ -288,7 +288,7 @@ if [[ -z "$TARGET_BRANCH" ]]; then
   fi
 
   printf '%s\n' "$start_output"
-  TARGET_BRANCH="$(printf '%s\n' "$start_output" | sed -n 's/^\[agent-branch-start\] Created branch: //p' | head -n 1)"
+  TARGET_BRANCH="$(printf '%s\n' "$start_output" | sed -n -E 's/^\[agent-branch-start\] (Created branch|Reusing existing branch): //p' | head -n 1)"
   target_worktree="$(printf '%s\n' "$start_output" | sed -n 's/^\[agent-branch-start\] Worktree: //p' | head -n 1)"
   if [[ -z "$TARGET_BRANCH" || -z "$target_worktree" ]]; then
     echo "[agent-branch-merge] Unable to parse target branch/worktree from agent-branch-start output." >&2

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

@@ -15,6 +15,7 @@ OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
 OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CAPABILITY_SLUG:-}"
 OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
 OPENSPEC_TIER_RAW="${GUARDEX_OPENSPEC_TIER:-T3}"
+REUSE_EXISTING_RAW="${GUARDEX_BRANCH_START_REUSE_EXISTING:-true}"
 PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()
 
@@ -58,6 +59,14 @@ while [[ $# -gt 0 ]]; do
       OPENSPEC_TIER_RAW="${2:-$OPENSPEC_TIER_RAW}"
       shift 2
       ;;
+    --reuse-existing|--reuse)
+      REUSE_EXISTING_RAW="true"
+      shift
+      ;;
+    --new|--no-reuse|--no-reuse-existing)
+      REUSE_EXISTING_RAW="false"
+      shift
+      ;;
     --in-place|--allow-in-place)
       echo "[agent-branch-start] In-place branch mode is disabled." >&2
       echo "[agent-branch-start] This command always creates an isolated worktree to keep your active checkout unchanged." >&2
@@ -78,7 +87,7 @@ while [[ $# -gt 0 ]]; do
       ;;
     -*)
       echo "[agent-branch-start] Unknown option: $1" >&2
-      echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>] [--print-name-only]" >&2
+      echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>] [--reuse-existing|--new] [--print-name-only]" >&2
       exit 1
       ;;
     *)
@@ -90,7 +99,7 @@ done
 
 if [[ "${#POSITIONAL_ARGS[@]}" -gt 3 ]]; then
   echo "[agent-branch-start] Too many positional arguments." >&2
-  echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>]" >&2
+  echo "Usage: $0 [task] [agent] [base] [--worktree-root <path>] [--reuse-existing|--new]" >&2
   exit 1
 fi
 
@@ -254,6 +263,7 @@ normalize_bool() {
 }
 
 OPENSPEC_AUTO_INIT="$(normalize_bool "$OPENSPEC_AUTO_INIT_RAW" "1")"
+REUSE_EXISTING_WORKTREE="$(normalize_bool "$REUSE_EXISTING_RAW" "1")"
 
 normalize_tier() {
   local raw="${1:-}"
@@ -370,6 +380,22 @@ resolve_worktree_leaf() {
   printf '%s' "${branch_name//\//__}"
 }
 
+print_reused_agent_worktree() {
+  local branch_name="$1"
+  local worktree_path="$2"
+
+  echo "[agent-branch-start] Reusing existing branch: ${branch_name}"
+  echo "[agent-branch-start] Worktree: ${worktree_path}"
+  echo "[agent-branch-start] OpenSpec tier: ${OPENSPEC_TIER}"
+  echo "[agent-branch-start] OpenSpec change: existing worktree"
+  echo "[agent-branch-start] OpenSpec plan: existing worktree"
+  echo "[agent-branch-start] Next steps:"
+  echo "  cd \"${worktree_path}\""
+  echo "  gx locks claim --branch \"${branch_name}\" <file...>"
+  echo "  # continue work in this existing sandbox"
+  echo "  gx branch finish --branch \"${branch_name}\" --via-pr --wait-for-merge"
+}
+
 has_local_changes() {
   local root="$1"
   if ! git -C "$root" diff --quiet; then
@@ -384,6 +410,101 @@ has_local_changes() {
   return 1
 }
 
+meaningful_slug_tokens() {
+  local raw="$1"
+  printf '%s' "$raw" \
+    | tr '[:upper:]' '[:lower:]' \
+    | tr '/_' '--' \
+    | tr '-' '\n' \
+    | awk '
+      length($0) < 4 { next }
+      $0 ~ /^[0-9]+$/ { next }
+      $0 ~ /^(agent|agents|branch|codex|claude|continue|dirty|existing|fix|from|implement|make|matching|reuse|start|task|that|this|update|with|worktree|worktrees)$/ { next }
+      !seen[$0]++ { print }
+    '
+}
+
+token_match_score() {
+  local task_slug="$1"
+  local branch_descriptor="$2"
+  local task_tokens branch_tokens token score
+  task_tokens="$(meaningful_slug_tokens "$task_slug")"
+  branch_tokens="$(meaningful_slug_tokens "$branch_descriptor")"
+  score=0
+
+  if [[ -z "$task_tokens" ]] || [[ -z "$branch_tokens" ]]; then
+    printf '0'
+    return 0
+  fi
+
+  while IFS= read -r token; do
+    if grep -Fxq "$token" <<<"$branch_tokens"; then
+      score=$((score + 1))
+    fi
+  done <<<"$task_tokens"
+
+  printf '%s' "$score"
+}
+
+managed_worktree_roots() {
+  local repo="$1"
+  local explicit_root="$2"
+  local root
+  local seen_roots=$'\n'
+
+  for root in \
+    "${repo}/${explicit_root}" \
+    "${repo}/.omx/agent-worktrees" \
+    "${repo}/.omc/agent-worktrees"; do
+    if [[ -n "$root" && "$seen_roots" != *$'\n'"$root"$'\n'* ]]; then
+      seen_roots+="${root}"$'\n'
+      printf '%s\n' "$root"
+    fi
+  done
+}
+
+find_matching_dirty_agent_worktree() {
+  local repo="$1"
+  local worktree_root_rel="$2"
+  local task_slug="$3"
+  local agent_slug="$4"
+  local best_score=0
+  local best_branch=""
+  local best_worktree=""
+  local best_count=0
+  local root entry branch descriptor score
+
+  while IFS= read -r root; do
+    [[ -d "$root" ]] || continue
+    while IFS= read -r entry; do
+      [[ -d "$entry" ]] || continue
+      if ! branch="$(git -C "$entry" rev-parse --abbrev-ref HEAD 2>/dev/null)"; then
+        continue
+      fi
+      [[ "$branch" == "agent/${agent_slug}/"* ]] || continue
+      has_local_changes "$entry" || continue
+
+      descriptor="${branch#agent/${agent_slug}/}"
+      score="$(token_match_score "$task_slug" "$descriptor")"
+      [[ "$score" =~ ^[0-9]+$ ]] || score=0
+      [[ "$score" -gt 0 ]] || continue
+
+      if [[ "$score" -gt "$best_score" ]]; then
+        best_score="$score"
+        best_branch="$branch"
+        best_worktree="$entry"
+        best_count=1
+      elif [[ "$score" -eq "$best_score" ]]; then
+        best_count=$((best_count + 1))
+      fi
+    done < <(find "$root" -mindepth 1 -maxdepth 1 -type d -print 2>/dev/null | sort)
+  done < <(managed_worktree_roots "$repo" "$worktree_root_rel")
+
+  if [[ "$best_score" -gt 0 && "$best_count" -eq 1 && -n "$best_branch" && -n "$best_worktree" ]]; then
+    printf '%s\t%s\n' "$best_branch" "$best_worktree"
+  fi
+}
+
 resolve_stash_ref_by_message() {
   local root="$1"
   local message="$2"
@@ -550,6 +671,12 @@ if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
   exit 1
 fi
 
+current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+if [[ "$REUSE_EXISTING_WORKTREE" -eq 1 && "$current_branch" == agent/* ]]; then
+  print_reused_agent_worktree "$current_branch" "$repo_root"
+  exit 0
+fi
+
 task_slug="$(sanitize_slug "$TASK_NAME" "task")"
 agent_slug="$(normalize_role "$AGENT_NAME")"
 if [[ "$WORKTREE_ROOT_EXPLICIT" -eq 0 ]]; then
@@ -565,6 +692,16 @@ if [[ "$PRINT_NAME_ONLY" -eq 1 ]]; then
   exit 0
 fi
 
+if [[ "$REUSE_EXISTING_WORKTREE" -eq 1 ]]; then
+  matching_dirty_worktree="$(find_matching_dirty_agent_worktree "$repo_root" "$WORKTREE_ROOT_REL" "$task_slug" "$agent_slug")"
+  if [[ -n "$matching_dirty_worktree" ]]; then
+    IFS=$'\t' read -r reused_branch reused_worktree <<<"$matching_dirty_worktree"
+    echo "[agent-branch-start] Matched dirty managed worktree for requested task."
+    print_reused_agent_worktree "$reused_branch" "$reused_worktree"
+    exit 0
+  fi
+fi
+
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
   current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
   protected_branches_raw="$(resolve_protected_branches "$repo_root")"
@@ -681,6 +818,7 @@ if [[ -n "$auto_transfer_stash_ref" ]]; then
   fi
 fi
 
+hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" ".venv"
 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"

package/templates/vscode/guardex-active-agents/extension.js

@@ -2395,6 +2395,74 @@ function isPathWithin(parentPath, targetPath) {
   return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
 }
 
+function normalizeAbsolutePath(value) {
+  return typeof value === 'string' && value.trim() ? path.resolve(value) : '';
+}
+
+function isManagedWorktreePath(worktreePath) {
+  const normalizedWorktreePath = normalizeAbsolutePath(worktreePath);
+  if (!normalizedWorktreePath) {
+    return false;
+  }
+
+  return MANAGED_WORKTREE_RELATIVE_ROOTS.some((relativeRoot) => {
+    const normalizedRelativeRoot = path.normalize(relativeRoot);
+    const marker = `${path.sep}${normalizedRelativeRoot}${path.sep}`;
+    return normalizedWorktreePath.includes(marker);
+  });
+}
+
+function removeDeletedWorktreeWorkspaceFolder(worktreePath) {
+  if (typeof vscode.workspace.updateWorkspaceFolders !== 'function') {
+    return false;
+  }
+
+  const normalizedWorktreePath = normalizeAbsolutePath(worktreePath);
+  if (!normalizedWorktreePath) {
+    return false;
+  }
+
+  const workspaceFolders = vscode.workspace.workspaceFolders || [];
+  const folderIndex = workspaceFolders.findIndex((folder) => (
+    normalizeAbsolutePath(folder?.uri?.fsPath) === normalizedWorktreePath
+  ));
+  if (folderIndex < 0) {
+    return false;
+  }
+
+  try {
+    return vscode.workspace.updateWorkspaceFolders(folderIndex, 1) === true;
+  } catch (_error) {
+    return false;
+  }
+}
+
+async function closeDeletedWorktreeRepository(worktreePath) {
+  const normalizedWorktreePath = normalizeAbsolutePath(worktreePath);
+  if (!normalizedWorktreePath || fs.existsSync(normalizedWorktreePath)) {
+    return false;
+  }
+
+  try {
+    await vscode.commands.executeCommand('git.close', vscode.Uri.file(normalizedWorktreePath));
+  } catch (_error) {
+    // The Git extension may have already removed this repository.
+  }
+
+  removeDeletedWorktreeWorkspaceFolder(normalizedWorktreePath);
+  return true;
+}
+
+function findDeletedManagedWorkspaceFolders() {
+  return (vscode.workspace.workspaceFolders || [])
+    .map((folder) => normalizeAbsolutePath(folder?.uri?.fsPath))
+    .filter((workspacePath) => (
+      workspacePath
+      && !fs.existsSync(workspacePath)
+      && isManagedWorktreePath(workspacePath)
+    ));
+}
+
 function localizeChangeForSession(session, change) {
   if (!change?.absolutePath || !isPathWithin(session.worktreePath, change.absolutePath)) {
     return null;
@@ -3434,6 +3502,8 @@ class ActiveAgentsRefreshController {
     this.inspectPanelManager = inspectPanelManager;
     this.refreshTimer = null;
     this.sessionWatchers = new Map();
+    this.closedMissingWorktreeRepositories = new Set();
+    this.observedWorktreePaths = new Set();
   }
 
   scheduleRefresh() {
@@ -3456,8 +3526,23 @@ class ActiveAgentsRefreshController {
     const repoEntries = await findRepoSessionEntries();
     const liveSessionKeys = new Set();
 
+    for (const workspacePath of findDeletedManagedWorkspaceFolders()) {
+      await this.closeMissingWorktreeRepository(workspacePath);
+    }
+
     for (const entry of repoEntries) {
       for (const session of entry.sessions) {
+        const worktreePath = sessionWorktreePath(session);
+        const normalizedWorktreePath = normalizeAbsolutePath(worktreePath);
+        if (normalizedWorktreePath && !fs.existsSync(normalizedWorktreePath)) {
+          await this.closeMissingWorktreeRepository(normalizedWorktreePath);
+          continue;
+        }
+        if (normalizedWorktreePath) {
+          this.closedMissingWorktreeRepositories.delete(normalizedWorktreePath);
+          this.observedWorktreePaths.add(normalizedWorktreePath);
+        }
+
         const sessionKey = resolveSessionWatcherKey(session);
         liveSessionKeys.add(sessionKey);
         if (this.sessionWatchers.has(sessionKey)) {
@@ -3468,8 +3553,20 @@ class ActiveAgentsRefreshController {
           resolveSessionGitIndexPath(session.worktreePath),
         );
         const disposables = bindRefreshWatcher(watcher, () => this.scheduleRefresh());
-        this.sessionWatchers.set(sessionKey, { watcher, disposables });
+        this.sessionWatchers.set(sessionKey, {
+          watcher,
+          disposables,
+          worktreePath: normalizedWorktreePath,
+        });
+      }
+    }
+
+    for (const observedWorktreePath of this.observedWorktreePaths) {
+      if (fs.existsSync(observedWorktreePath)) {
+        this.closedMissingWorktreeRepositories.delete(observedWorktreePath);
+        continue;
       }
+      await this.closeMissingWorktreeRepository(observedWorktreePath);
     }
 
     for (const [sessionKey, entry] of this.sessionWatchers) {
@@ -3477,12 +3574,25 @@ class ActiveAgentsRefreshController {
         continue;
       }
 
+      if (entry.worktreePath && !fs.existsSync(entry.worktreePath)) {
+        await this.closeMissingWorktreeRepository(entry.worktreePath);
+      }
       disposeAll(entry.disposables);
       entry.watcher.dispose();
       this.sessionWatchers.delete(sessionKey);
     }
   }
 
+  async closeMissingWorktreeRepository(worktreePath) {
+    const normalizedWorktreePath = normalizeAbsolutePath(worktreePath);
+    if (!normalizedWorktreePath || this.closedMissingWorktreeRepositories.has(normalizedWorktreePath)) {
+      return;
+    }
+
+    this.closedMissingWorktreeRepositories.add(normalizedWorktreePath);
+    await closeDeletedWorktreeRepository(normalizedWorktreePath);
+  }
+
   dispose() {
     if (this.refreshTimer) {
       clearTimeout(this.refreshTimer);

package/templates/vscode/guardex-active-agents/package.json

@@ -3,7 +3,7 @@
   "displayName": "GitGuardex Active Agents",
   "description": "Shows live Guardex sandbox sessions and repo changes in a dedicated VS Code Active Agents sidebar.",
   "publisher": "Recodee",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "license": "MIT",
   "icon": "icon.png",
   "engines": {