@imdeadpool/guardex 7.0.36 → 7.0.38

package/README.md

@@ -266,6 +266,20 @@ Being honest about where this still has issues:
 <details open>
 <summary><strong>v7.x</strong></summary>
 
+### 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
+  the registry.
+- No new CLI command behavior is introduced in this release lane.
+
+### v7.0.37
+- Bumped `@imdeadpool/guardex` from `7.0.36` to `7.0.37` so the current
+  package can publish under a fresh npm version after `7.0.36` reached the
+  registry.
+- Synced the shipped Active Agents template with the canonical VS Code
+  extension source so Colony task counts and details install with the package.
+- No new CLI command behavior is introduced in this release lane.
+
 ### v7.0.36
 - Bumped `@imdeadpool/guardex` from `7.0.35` to `7.0.36` so the latest
   branch-finish cwd-prune fix can ship under a fresh npm version after PR #424.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.36",
+  "version": "7.0.38",
   "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

@@ -656,7 +656,7 @@ function runSetupInSandbox(options, blocked, repoLabel = '') {
   const nestedResult = run(
     process.execPath,
     [__filename, ...buildSandboxSetupArgs(options, sandboxTarget)],
-    { cwd: metadata.worktreePath },
+    { cwd: metadata.worktreePath, env: { GUARDEX_DOCTOR_SANDBOX: '1' } },
   );
   if (isSpawnFailure(nestedResult)) {
     throw nestedResult.error;
@@ -701,6 +701,12 @@ function runSetupInSandbox(options, blocked, repoLabel = '') {
     console.log(`[${TOOL_NAME}] ${autoFinishSummary.details[0]}`);
   }
 
+  const prunePayload = doctorModule.pruneStaleAgentWorktrees(scanResult.repoRoot, {
+    baseBranch: currentBaseBranch,
+    dryRun: syncOptions.dryRun,
+  });
+  printWorktreePruneSummary(prunePayload, { baseBranch: currentBaseBranch });
+
   const cleanupResult = cleanupProtectedBaseSandbox(blocked.repoRoot, metadata);
   console.log(
     `[${TOOL_NAME}] Protected-base setup sandbox cleanup: ${cleanupResult.note} ` +
@@ -1755,6 +1761,26 @@ function runScanInternal(options) {
   };
 }
 
+function printWorktreePruneSummary(payload, options = {}) {
+  if (!payload || payload.enabled === false) {
+    if (payload && payload.details && payload.details[0]) {
+      console.log(`[${TOOL_NAME}] ${payload.details[0]}`);
+    }
+    return;
+  }
+  if (!payload.ran) {
+    return;
+  }
+  const baseLabel = options.baseBranch ? ` (base=${options.baseBranch})` : '';
+  const tag = payload.status === 'failed' ? '⚠️' : (payload.status === 'dry-run' ? '🔍' : '🧹');
+  console.log(
+    `[${TOOL_NAME}] ${tag} Stale agent-worktree prune${baseLabel}: status=${payload.status}`,
+  );
+  for (const detail of payload.details || []) {
+    console.log(`[${TOOL_NAME}]   ${detail}`);
+  }
+}
+
 function printScanResult(scan, json = false) {
   if (json) {
     process.stdout.write(
@@ -2369,6 +2395,12 @@ function doctor(rawArgs) {
       configureHooks,
       autoFinishReadyAgentBranches: doctorModule.autoFinishReadyAgentBranches,
     });
+    const primaryBaseBranch = currentBranchName(blocked.repoRoot);
+    const prunePayload = doctorModule.pruneStaleAgentWorktrees(blocked.repoRoot, {
+      baseBranch: primaryBaseBranch,
+      dryRun: singleRepoOptions.dryRun,
+    });
+    printWorktreePruneSummary(prunePayload, { baseBranch: primaryBaseBranch });
     return;
   }
 
@@ -2390,6 +2422,12 @@ function doctor(rawArgs) {
       dryRun: singleRepoOptions.dryRun,
       waitForMerge: singleRepoOptions.waitForMerge,
     });
+  const prunePayload = scanResult.guardexEnabled === false
+    ? { enabled: false, ran: false, status: 'skipped', details: ['Guardex disabled for this repo.'] }
+    : doctorModule.pruneStaleAgentWorktrees(scanResult.repoRoot, {
+      baseBranch: currentBaseBranch,
+      dryRun: singleRepoOptions.dryRun,
+    });
   const safe = scanResult.guardexEnabled === false || (scanResult.errors === 0 && scanResult.warnings === 0);
   const musafe = safe;
 
@@ -2414,6 +2452,7 @@ function doctor(rawArgs) {
             findings: scanResult.findings,
           },
           autoFinish: autoFinishSummary,
+          worktreePrune: prunePayload,
         },
         null,
         2,
@@ -2434,6 +2473,7 @@ function doctor(rawArgs) {
     baseBranch: currentBaseBranch,
     verbose: singleRepoOptions.verboseAutoFinish,
   });
+  printWorktreePruneSummary(prunePayload, { baseBranch: currentBaseBranch });
   if (safe) {
     console.log(colorizeDoctorOutput(`[${TOOL_NAME}] ✅ Repo is fully safe.`, 'safe'));
   } else {
@@ -2967,6 +3007,12 @@ function setup(rawArgs) {
       aggregateErrors += sandboxResult.scanResult.errors;
       aggregateWarnings += sandboxResult.scanResult.warnings;
       lastScanResult = sandboxResult.scanResult;
+      const primaryBaseBranch = currentBranchName(blocked.repoRoot);
+      const prunePayload = doctorModule.pruneStaleAgentWorktrees(blocked.repoRoot, {
+        baseBranch: primaryBaseBranch,
+        dryRun: perRepoOptions.dryRun,
+      });
+      printWorktreePruneSummary(prunePayload, { baseBranch: primaryBaseBranch });
       continue;
     }
 
@@ -2992,6 +3038,13 @@ function setup(rawArgs) {
     printAutoFinishSummary(autoFinishSummary, {
       baseBranch: currentBaseBranch,
     });
+    const prunePayload = scanResult.guardexEnabled === false
+      ? { enabled: false, ran: false, status: 'skipped', details: ['Guardex disabled for this repo.'] }
+      : doctorModule.pruneStaleAgentWorktrees(scanResult.repoRoot, {
+        baseBranch: currentBaseBranch,
+        dryRun: perRepoOptions.dryRun,
+      });
+    printWorktreePruneSummary(prunePayload, { baseBranch: currentBaseBranch });
     printSetupRepoHints(scanResult.repoRoot, currentBaseBranch, repoLabel);
 
     aggregateErrors += scanResult.errors;
@@ -3380,6 +3433,64 @@ function branch(rawArgs) {
   );
 }
 
+// `gx pivot` — single-tool-call escape from a protected branch into an isolated
+// agent worktree. AI agents (Claude Code / Codex) cannot set the bypass env
+// vars from inside a tool call, so they need a whitelisted command that does
+// the whole hop: branch+worktree creation, dirty-tree migration, and a clean
+// trailer (`WORKTREE_PATH=...`, `BRANCH=...`, `NEXT_STEP=cd ...`) the agent can
+// parse to know exactly where to `cd`.
+//
+// On an existing agent/* branch, `gx pivot` short-circuits and just prints the
+// current worktree path — safe to call as a no-op.
+function pivot(rawArgs) {
+  const { target, passthrough } = extractTargetedArgs(rawArgs);
+  const repoRoot = resolveRepoRoot(target);
+  const headProc = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoRoot });
+  const currentBranch = String(headProc.stdout || '').trim();
+  if (currentBranch.startsWith('agent/')) {
+    const wtProc = run('git', ['rev-parse', '--show-toplevel'], { cwd: repoRoot });
+    const wtPath = String(wtProc.stdout || '').trim() || repoRoot;
+    process.stdout.write(`[${TOOL_NAME} pivot] Already on agent branch '${currentBranch}'.\n`);
+    process.stdout.write(`WORKTREE_PATH=${wtPath}\n`);
+    process.stdout.write(`BRANCH=${currentBranch}\n`);
+    process.stdout.write(`NEXT_STEP=cd "${wtPath}"\n`);
+    process.exitCode = 0;
+    return;
+  }
+  const result = runPackageAsset('branchStart', passthrough, { cwd: repoRoot });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.status !== 0) {
+    process.exitCode = result.status || 1;
+    return;
+  }
+  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);
+  if (wtMatch) {
+    const wtPath = wtMatch[1].trim();
+    process.stdout.write('\n');
+    process.stdout.write(`WORKTREE_PATH=${wtPath}\n`);
+    if (branchMatch) process.stdout.write(`BRANCH=${branchMatch[1].trim()}\n`);
+    process.stdout.write(`NEXT_STEP=cd "${wtPath}"\n`);
+  }
+  process.exitCode = 0;
+}
+
+// `gx ship` — alias for the canonical "I am done" command. Defaults to
+// `finish --via-pr --wait-for-merge --cleanup` so AI agents don't strand
+// commits or worktrees by accident. Any explicit user-supplied flags survive.
+function ship(rawArgs) {
+  const args = Array.isArray(rawArgs) ? rawArgs.slice() : [];
+  const ensureFlag = (flag) => {
+    if (!args.includes(flag)) args.push(flag);
+  };
+  ensureFlag('--via-pr');
+  ensureFlag('--wait-for-merge');
+  ensureFlag('--cleanup');
+  return finish(args);
+}
+
 function locks(rawArgs) {
   const { target, passthrough } = extractTargetedArgs(rawArgs);
   const result = runPackageAsset('lockTool', passthrough, { cwd: resolveRepoRoot(target) });
@@ -3637,6 +3748,8 @@ async function main() {
   if (command === 'prompt') return prompt(rest);
   if (command === 'doctor') return doctor(rest);
   if (command === 'branch') return branch(rest);
+  if (command === 'pivot') return pivot(rest);
+  if (command === 'ship') return ship(rest);
   if (command === 'locks') return locks(rest);
   if (command === 'worktree') return worktree(rest);
   if (command === 'hook') return hook(rest);

package/src/context.js

@@ -338,6 +338,8 @@ const SUGGESTIBLE_COMMANDS = [
   'setup',
   'doctor',
   'branch',
+  'pivot',
+  'ship',
   'locks',
   'worktree',
   'hook',
@@ -383,7 +385,9 @@ const CLI_COMMAND_GROUPS = [
     label: 'Branch workflow',
     description: 'The sandbox → commit → PR → merge loop for agent-owned branches.',
     commands: [
+      ['pivot', 'Auto-pivot from a protected branch into a fresh agent worktree (single tool call for AI agents)'],
       ['branch', 'CLI-owned branch workflow surface (start/finish/merge)'],
+      ['ship', 'Stage + commit + push + PR + auto-merge + cleanup (alias for `finish --via-pr --wait-for-merge --cleanup`)'],
       ['finish', 'Commit + PR + merge completed agent branches (--all, --branch)'],
       ['merge', 'Create/reuse an integration lane and merge overlapping agent branches'],
       ['sync', 'Sync agent branches with origin/<base>'],

package/src/doctor/index.js

@@ -1006,6 +1006,70 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
   return summary;
 }
 
+function pruneStaleAgentWorktrees(repoRoot, options = {}) {
+  const summary = {
+    enabled: true,
+    ran: false,
+    status: 'skipped',
+    details: [],
+  };
+
+  const dryRun = Boolean(options.dryRun);
+  const baseBranch = String(options.baseBranch || '').trim();
+
+  if (String(process.env.GUARDEX_DOCTOR_SANDBOX || '') === '1') {
+    summary.enabled = false;
+    summary.details.push('Skipped stale-worktree prune inside doctor sandbox pass.');
+    return summary;
+  }
+
+  if (String(process.env.GUARDEX_SKIP_AUTO_WORKTREE_PRUNE || '') === '1') {
+    summary.enabled = false;
+    summary.details.push('Skipped stale-worktree prune (GUARDEX_SKIP_AUTO_WORKTREE_PRUNE=1).');
+    return summary;
+  }
+
+  const idleMinutesRaw = Number(options.idleMinutes);
+  const idleMinutes = Number.isFinite(idleMinutesRaw) && idleMinutesRaw >= 0
+    ? Math.floor(idleMinutesRaw)
+    : 60;
+
+  const args = [
+    '--idle-minutes', String(idleMinutes),
+    '--delete-branches',
+    '--delete-remote-branches',
+    '--include-pr-merged',
+    '--force-dirty',
+  ];
+  if (baseBranch && baseBranch !== 'HEAD' && !baseBranch.startsWith('agent/')) {
+    args.push('--base', baseBranch);
+  }
+  if (dryRun) {
+    args.push('--dry-run');
+  }
+
+  const runResult = runPackageAsset('worktreePrune', args, { cwd: repoRoot });
+  summary.ran = true;
+  const stdout = String(runResult.stdout || '').trim();
+  const stderr = String(runResult.stderr || '').trim();
+  if (stdout) {
+    for (const line of stdout.split('\n')) {
+      if (line.trim()) summary.details.push(line);
+    }
+  }
+  if (runResult.status === 0) {
+    summary.status = dryRun ? 'dry-run' : 'pruned';
+  } else {
+    summary.status = 'failed';
+    if (stderr) {
+      summary.details.push(`[error] ${stderr.split('\n').slice(-2).join(' | ')}`);
+    } else {
+      summary.details.push(`[error] worktreePrune exited with status ${runResult.status}`);
+    }
+  }
+  return summary;
+}
+
 function executeDoctorSandboxLifecycle(options, blocked, metadata, integrations) {
   const execution = createDoctorSandboxExecutionState();
   const dryRun = Boolean(options.dryRun);
@@ -1206,7 +1270,7 @@ function runDoctorInSandbox(options, blocked, rawIntegrations = {}) {
   const nestedResult = run(
     process.execPath,
     [require.main?.filename || process.argv[1], ...buildSandboxDoctorArgs(options, sandboxTarget)],
-    { cwd: metadata.worktreePath },
+    { cwd: metadata.worktreePath, env: { GUARDEX_DOCTOR_SANDBOX: '1' } },
   );
   if (isSpawnFailure(nestedResult)) {
     throw nestedResult.error;
@@ -1242,5 +1306,6 @@ module.exports = {
   emitDoctorSandboxJsonOutput,
   emitDoctorSandboxConsoleOutput,
   autoFinishReadyAgentBranches,
+  pruneStaleAgentWorktrees,
   runDoctorInSandbox,
 };

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

@@ -165,7 +165,11 @@ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
 fi
 
 repo_root="$(git rev-parse --show-toplevel)"
-current_worktree="$(pwd -P)"
+# The physical cwd may be a subdirectory inside the source worktree. Cleanup
+# decisions need the enclosing worktree root, otherwise finishing from `src/`
+# can delete the caller's cwd and turn a successful merge into a false shell
+# failure.
+current_worktree="$repo_root"
 common_git_dir_raw="$(git -C "$repo_root" rev-parse --git-common-dir)"
 if [[ "$common_git_dir_raw" == /* ]]; then
   common_git_dir="$common_git_dir_raw"
@@ -223,7 +227,68 @@ if [[ "$SOURCE_BRANCH" == "$BASE_BRANCH" ]]; then
   exit 1
 fi
 
+cleanup_missing_merged_source_branch() {
+  local state_line=""
+  local parsed_state=""
+  local parsed_merged_at=""
+  local parsed_url=""
+  local remote_delete_output=""
+  local prune_args=()
+
+  if [[ "$MERGE_MODE" != "pr" || "$CLEANUP_AFTER_MERGE" -ne 1 ]]; then
+    return 1
+  fi
+  if ! command -v "$GH_BIN" >/dev/null 2>&1; then
+    return 1
+  fi
+
+  state_line="$("$GH_BIN" pr list \
+    --state merged \
+    --head "$SOURCE_BRANCH" \
+    --base "$BASE_BRANCH" \
+    --json state,mergedAt,url \
+    --jq 'sort_by(.mergedAt // "") | reverse | (.[0] // {}) | [(.state // ""), (.mergedAt // ""), (.url // "")] | join("\u001f")' \
+    2>/dev/null || true)"
+  if [[ -z "$state_line" ]]; then
+    return 1
+  fi
+
+  IFS=$'\x1f' read -r parsed_state parsed_merged_at parsed_url <<< "$state_line"
+  if [[ "$parsed_state" != "MERGED" && -z "$parsed_merged_at" ]]; then
+    return 1
+  fi
+
+  echo "[agent-branch-finish] Local source branch '${SOURCE_BRANCH}' is already absent, but a merged PR exists; continuing cleanup." >&2
+  if [[ -n "$parsed_url" ]]; then
+    echo "[agent-branch-finish] Merged PR: ${parsed_url}" >&2
+  fi
+
+  run_guardex_cli locks release --branch "$SOURCE_BRANCH" >/dev/null 2>&1 || true
+
+  if [[ "$PUSH_ENABLED" -eq 1 && "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
+    if git -C "$repo_root" ls-remote --exit-code --heads origin "$SOURCE_BRANCH" >/dev/null 2>&1; then
+      if ! remote_delete_output="$(git -C "$repo_root" push origin --delete "$SOURCE_BRANCH" 2>&1)"; then
+        echo "[agent-branch-finish] Warning: remote branch cleanup failed for '${SOURCE_BRANCH}'." >&2
+        [[ -n "$remote_delete_output" ]] && echo "$remote_delete_output" >&2
+      fi
+    fi
+  fi
+
+  prune_args=(worktree prune --base "$BASE_BRANCH" --only-dirty-worktrees --delete-branches)
+  if [[ "$DELETE_REMOTE_BRANCH" -eq 1 ]]; then
+    prune_args+=(--delete-remote-branches)
+  fi
+  if ! run_guardex_cli "${prune_args[@]}"; then
+    echo "[agent-branch-finish] Warning: automatic worktree prune failed." >&2
+    echo "[agent-branch-finish] You can run manual cleanup: gx cleanup --base ${BASE_BRANCH}" >&2
+  fi
+
+  echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via pr flow and found source branch/worktree already cleaned."
+  exit 0
+}
+
 if ! git -C "$repo_root" show-ref --verify --quiet "refs/heads/${SOURCE_BRANCH}"; then
+  cleanup_missing_merged_source_branch
   echo "[agent-branch-finish] Local source branch does not exist: ${SOURCE_BRANCH}" >&2
   exit 1
 fi
@@ -846,10 +911,12 @@ if [[ "$CLEANUP_AFTER_MERGE" -eq 1 ]]; then
     echo "[agent-branch-finish] You can run manual cleanup: gx cleanup --base ${BASE_BRANCH}" >&2
   fi
 
-  echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via ${merge_status} flow and cleaned source branch/worktree."
   if [[ "$source_worktree" == "$current_worktree" && "$source_worktree" == "${agent_worktree_root}"/* && -d "$source_worktree" ]]; then
+    echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via ${merge_status} flow and cleaned source branch/remote."
     echo "[agent-branch-finish] Current worktree '${source_worktree}' still exists because it is the active shell cwd." >&2
     echo "[agent-branch-finish] Leave this directory, then run: gx cleanup --base ${BASE_BRANCH}" >&2
+  else
+    echo "[agent-branch-finish] Merged '${SOURCE_BRANCH}' into '${BASE_BRANCH}' via ${merge_status} flow and cleaned source branch/worktree."
   fi
 else
   pivot_to_repo_root_before_prune

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

@@ -1,6 +1,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const cp = require('node:child_process');
+const http = require('node:http');
+const os = require('node:os');
 const vscode = require('vscode');
 const {
   clearWorktreeActivityCache,
@@ -40,6 +42,84 @@ const ACTIVE_AGENTS_EXTENSION_ID = 'Recodee.gitguardex-active-agents';
 const RESTART_EXTENSION_HOST_COMMAND = 'workbench.action.restartExtensionHost';
 const REFRESH_POLL_INTERVAL_MS = 30_000;
 const INSPECT_PANEL_VIEW_TYPE = 'gitguardex.activeAgents.inspect';
+const COLONY_DEFAULT_PORT = 37777;
+const COLONY_SNAPSHOT_TTL_MS = 5_000;
+const COLONY_FETCH_TIMEOUT_MS = 800;
+
+function colonyDataDir() {
+  return process.env.COLONY_HOME
+    || process.env.CAVEMEM_HOME
+    || path.join(os.homedir(), '.colony');
+}
+
+function readColonyPort() {
+  try {
+    const raw = fs.readFileSync(path.join(colonyDataDir(), 'settings.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    const port = Number(parsed?.workerPort);
+    return Number.isFinite(port) && port > 0 ? port : COLONY_DEFAULT_PORT;
+  } catch (_error) {
+    return COLONY_DEFAULT_PORT;
+  }
+}
+
+function fetchColonyJson(urlPath) {
+  return new Promise((resolve) => {
+    const req = http.get(
+      {
+        hostname: '127.0.0.1',
+        port: readColonyPort(),
+        path: urlPath,
+        timeout: COLONY_FETCH_TIMEOUT_MS,
+      },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          resolve(null);
+          return;
+        }
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          body += chunk;
+        });
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(body));
+          } catch (_error) {
+            resolve(null);
+          }
+        });
+      },
+    );
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+const colonyTasksCache = new Map();
+
+async function readColonyTasksForRepo(repoRoot) {
+  const cached = colonyTasksCache.get(repoRoot);
+  if (cached && Date.now() - cached.at < COLONY_SNAPSHOT_TTL_MS) {
+    return cached.tasks;
+  }
+  const tasks = await fetchColonyJson(
+    `/api/colony/tasks?repo_root=${encodeURIComponent(repoRoot)}`,
+  );
+  const resolved = Array.isArray(tasks) ? tasks : [];
+  colonyTasksCache.set(repoRoot, { at: Date.now(), tasks: resolved });
+  return resolved;
+}
+
+function compactColonyBranchLabel(branch) {
+  if (typeof branch !== 'string' || !branch) return 'unknown';
+  const parts = branch.split('/').filter(Boolean);
+  return parts.length > 2 ? parts.slice(-2).join('/') : branch;
+}
 const GIT_CONFIGURATION_SECTION = 'git';
 const REPO_SCAN_IGNORED_FOLDERS_SETTING = 'repositoryScanIgnoredFolders';
 const BUNDLED_FILE_ICONS_MANIFEST_RELATIVE = path.join('fileicons', 'gitguardex-fileicons.json');
@@ -56,7 +136,7 @@ const MANAGED_REPO_SCAN_IGNORED_FOLDERS = [
 const SESSION_ACTIVITY_GROUPS = [
   { kind: 'blocked', label: 'BLOCKED' },
   { kind: 'working', label: 'WORKING NOW' },
-  { kind: 'finished', label: 'FINISHED' },
+  { kind: 'finished', label: 'NEEDS CLEANUP' },
   { kind: 'idle', label: 'THINKING' },
   { kind: 'stalled', label: 'STALLED' },
   { kind: 'dead', label: 'DEAD' },
@@ -491,7 +571,7 @@ function buildActiveAgentsStatusSummary(summary) {
   if (workingCount > 0 || finishedCount > 0 || idleCount > 0) {
     const parts = [`${workingCount} working`];
     if (finishedCount > 0) {
-      parts.push(`${finishedCount} finished`);
+      parts.push(`${finishedCount} needs cleanup`);
     }
     parts.push(`${idleCount} idle`);
     return `$(git-branch) ${parts.join(' · ')}`;
@@ -514,7 +594,7 @@ function buildActiveAgentsStatusTooltip(selectedSession, summary) {
   return [
     formatCountLabel(activeCount, 'active agent'),
     formatCountLabel(summary?.workingCount || 0, 'working now session', 'working now sessions'),
-    formatCountLabel(summary?.finishedCount || 0, 'finished session'),
+    formatCountLabel(summary?.finishedCount || 0, 'needs cleanup session'),
     formatCountLabel(summary?.idleCount || 0, 'idle session'),
     formatCountLabel(summary?.unassignedChangeCount || 0, 'unassigned change'),
     formatCountLabel(summary?.lockedFileCount || 0, 'locked file'),
@@ -601,7 +681,7 @@ function sessionFreshnessLabel(session, now = Date.now()) {
     return 'Needs attention';
   }
   if (session.activityKind === 'finished') {
-    return 'Finished';
+    return 'Needs cleanup';
   }
   if (session.activityKind === 'stalled') {
     return 'Possibly stale';
@@ -631,7 +711,7 @@ function sessionStatusLabel(session) {
     case 'working':
       return 'Working';
     case 'finished':
-      return 'Finished';
+      return 'Needs cleanup';
     case 'idle':
       return 'Idle';
     case 'stalled':
@@ -838,12 +918,20 @@ function buildWorktreeBranchDescription(sessions) {
 function buildOverviewDescription(summary) {
   return [
     formatCountLabel(summary?.workingCount || 0, 'working agent'),
-    formatCountLabel(summary?.finishedCount || 0, 'finished agent'),
+    formatCountLabel(summary?.finishedCount || 0, 'needs cleanup agent'),
     formatCountLabel(summary?.idleCount || 0, 'idle agent'),
+    summary?.colonyTaskCount
+      ? formatCountLabel(summary.colonyTaskCount, 'colony task')
+      : '',
+    summary?.pendingHandoffCount
+      ? formatCountLabel(summary.pendingHandoffCount, 'pending handoff')
+      : '',
     formatCountLabel(summary?.unassignedChangeCount || 0, 'unassigned change'),
     formatCountLabel(summary?.lockedFileCount || 0, 'locked file'),
     formatCountLabel(summary?.conflictCount || 0, 'conflict'),
-  ].join(' · ');
+  ]
+    .filter(Boolean)
+    .join(' · ');
 }
 
 function buildRepoDescription(summary) {
@@ -1252,7 +1340,9 @@ class RepoItem extends vscode.TreeItem {
     this.changes = changes;
     this.unassignedChanges = options.unassignedChanges || [];
     this.lockEntries = options.lockEntries || [];
-    this.overview = options.overview || buildRepoOverview(sessions, this.unassignedChanges, this.lockEntries);
+    this.colonyTasks = Array.isArray(options.colonyTasks) ? options.colonyTasks : [];
+    this.overview = options.overview
+      || buildRepoOverview(sessions, this.unassignedChanges, this.lockEntries, this.colonyTasks);
     this.description = buildRepoDescription(this.overview);
     this.tooltip = buildRepoTooltip(repoRoot, this.overview);
     this.iconPath = themeIcon('repo');
@@ -2524,7 +2614,8 @@ function countChangedPaths(repoRoot, sessions, changes) {
   return changedKeys.size;
 }
 
-function buildRepoOverview(sessions, unassignedChanges, lockEntries) {
+function buildRepoOverview(sessions, unassignedChanges, lockEntries, colonyTasks = []) {
+  const colonyTaskList = Array.isArray(colonyTasks) ? colonyTasks : [];
   return {
     sessionCount: sessions.length,
     workingCount: countWorkingSessions(sessions),
@@ -2536,6 +2627,11 @@ function buildRepoOverview(sessions, unassignedChanges, lockEntries) {
       (total, session) => total + (session.conflictCount || 0),
       0,
     ) + (unassignedChanges || []).filter((change) => change.hasForeignLock).length,
+    colonyTaskCount: colonyTaskList.length,
+    pendingHandoffCount: colonyTaskList.reduce(
+      (total, task) => total + (task.pending_handoff_count || 0),
+      0,
+    ),
   };
 }
 
@@ -2829,7 +2925,9 @@ function buildWorkingNowNodes(sessions) {
 function buildIdleThinkingNodes(sessions) {
   const sessionEntries = sortSessionsForIdleThinking(
     sessions.filter((session) => !(
-      session.activityKind === 'working' || session.activityKind === 'blocked'
+      session.activityKind === 'working'
+      || session.activityKind === 'blocked'
+      || session.activityKind === 'finished'
     )),
   ).map((session) => ({
     projectRelativePath: resolveSessionProjectRelativePath(session),
@@ -2839,6 +2937,17 @@ function buildIdleThinkingNodes(sessions) {
   return buildProjectScopedItems(sessionEntries, { rootLabel: 'Repo root' });
 }
 
+function buildNeedsCleanupNodes(sessions) {
+  const sessionEntries = sessions
+    .filter((session) => session.activityKind === 'finished')
+    .map((session) => ({
+      projectRelativePath: resolveSessionProjectRelativePath(session),
+      sessions: [session],
+      item: new SessionItem(session, buildSessionDetailItems(session)),
+    }));
+  return buildProjectScopedItems(sessionEntries, { rootLabel: 'Repo root' });
+}
+
 function buildUnassignedChangeNodes(changes) {
   return sortUnassignedChanges(changes).map((change) => new ChangeItem(change, {
     label: compactRelativePath(change.relativePath),
@@ -3023,12 +3132,14 @@ class ActiveAgentsProvider {
 
       const { repoRootChanges } = partitionChangesByOwnership(sessions, changes);
       const unassignedChanges = sortUnassignedChanges(repoRootChanges);
+      const colonyTasks = Array.isArray(entry.colonyTasks) ? entry.colonyTasks : [];
       return {
         ...entry,
         sessions,
         changes,
         unassignedChanges,
-        overview: buildRepoOverview(sessions, unassignedChanges, entry.lockEntries),
+        colonyTasks,
+        overview: buildRepoOverview(sessions, unassignedChanges, entry.lockEntries, colonyTasks),
       };
     });
 
@@ -3107,6 +3218,15 @@ class ActiveAgentsProvider {
         }));
       }
 
+      const needsCleanupItems = buildNeedsCleanupNodes(element.sessions);
+      if (needsCleanupItems.length > 0) {
+        sectionItems.push(new SectionItem('Needs cleanup', needsCleanupItems, {
+          description: String(needsCleanupItems.length),
+          collapsedState: vscode.TreeItemCollapsibleState.Collapsed,
+          iconId: 'pass-filled',
+        }));
+      }
+
       const idleThinkingItems = buildIdleThinkingNodes(element.sessions);
       if (idleThinkingItems.length > 0) {
         sectionItems.push(new SectionItem('Idle / thinking', idleThinkingItems, {
@@ -3140,6 +3260,37 @@ class ActiveAgentsProvider {
           iconId: 'file-directory',
         }));
       }
+      const colonyTaskList = Array.isArray(element.colonyTasks) ? element.colonyTasks : [];
+      if (colonyTaskList.length > 0) {
+        const colonyItems = colonyTaskList.map((task) => {
+          const pendingLabel = task.pending_handoff_count > 0
+            ? formatCountLabel(task.pending_handoff_count, 'pending handoff')
+            : 'quiet';
+          const participantLabel =
+            (task.participants || []).map((p) => p.agent).filter(Boolean).join(', ')
+            || 'no participants';
+          return new DetailItem(
+            `#${task.id} · ${compactColonyBranchLabel(task.branch)}`,
+            `${participantLabel} · ${pendingLabel}`,
+            {
+              iconId: task.pending_handoff_count > 0 ? 'warning' : 'comment-discussion',
+              tooltip: [
+                task.branch,
+                `task #${task.id}`,
+                participantLabel,
+                task.pending_handoff_count > 0
+                  ? formatCountLabel(task.pending_handoff_count, 'pending handoff')
+                  : '',
+              ].filter(Boolean).join('\n'),
+            },
+          );
+        });
+        advancedItems.push(new SectionItem('Colony tasks', colonyItems, {
+          description: String(colonyItems.length),
+          collapsedState: vscode.TreeItemCollapsibleState.Collapsed,
+          iconId: 'organization',
+        }));
+      }
       if (advancedItems.length > 0) {
         sectionItems.push(new SectionItem('Advanced details', advancedItems, {
           description: String(advancedItems.length),
@@ -3166,24 +3317,29 @@ class ActiveAgentsProvider {
       overview: entry.overview,
       unassignedChanges: entry.unassignedChanges,
       lockEntries: entry.lockEntries,
+      colonyTasks: entry.colonyTasks,
     }));
   }
 
   async loadRepoEntries() {
     const repoEntries = await findRepoSessionEntries();
-    return repoEntries.map((entry) => {
-      const repoRoot = entry.repoRoot;
-      const lockRegistry = this.getLockRegistryForRepo(repoRoot);
-      const currentBranch = readCurrentBranch(repoRoot);
-      return {
-        repoRoot,
-        sessions: entry.sessions.map((session) => decorateSession(session, lockRegistry)),
-        changes: readRepoChanges(repoRoot).map((change) => (
-          decorateChange(change, lockRegistry, currentBranch)
-        )),
-        lockEntries: Array.from(lockRegistry.entriesByPath.entries()),
-      };
-    });
+    return Promise.all(
+      repoEntries.map(async (entry) => {
+        const repoRoot = entry.repoRoot;
+        const lockRegistry = this.getLockRegistryForRepo(repoRoot);
+        const currentBranch = readCurrentBranch(repoRoot);
+        const colonyTasks = await readColonyTasksForRepo(repoRoot);
+        return {
+          repoRoot,
+          sessions: entry.sessions.map((session) => decorateSession(session, lockRegistry)),
+          changes: readRepoChanges(repoRoot).map((change) => (
+            decorateChange(change, lockRegistry, currentBranch)
+          )),
+          lockEntries: Array.from(lockRegistry.entriesByPath.entries()),
+          colonyTasks,
+        };
+      }),
+    );
   }
 }
 
@@ -3453,7 +3609,7 @@ function activate(context) {
     vscode.commands.registerCommand('gitguardex.activeAgents.refresh', refresh),
     vscode.commands.registerCommand('gitguardex.activeAgents.restart', restartActiveAgents),
     vscode.commands.registerCommand('gitguardex.activeAgents.focus', async () => {
-      await vscode.commands.executeCommand('workbench.view.extension.gitguardex.activeAgentsContainer');
+      await vscode.commands.executeCommand('workbench.view.extension.gitguardex-active-agents-container');
     }),
     vscode.commands.registerCommand('gitguardex.activeAgents.commitSelectedSession', commitSelectedSession),
     vscode.commands.registerCommand('gitguardex.activeAgents.openWorktree', async (session) => {

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.19",
+  "version": "0.0.20",
   "license": "MIT",
   "icon": "icon.png",
   "engines": {
@@ -79,14 +79,14 @@
     "viewsContainers": {
       "activitybar": [
         {
-          "id": "gitguardex.activeAgentsContainer",
+          "id": "gitguardex-active-agents-container",
           "title": "Active Agents",
           "icon": "media/active-agents-hivemind.svg"
         }
       ]
     },
     "views": {
-      "gitguardex.activeAgentsContainer": [
+      "gitguardex-active-agents-container": [
         {
           "id": "gitguardex.activeAgents",
           "name": "Active Agents",