@imdeadpool/guardex 7.0.27 → 7.0.31

package/README.md

@@ -708,6 +708,12 @@ npm pack --dry-run
 <details>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.28
+- Bumped `@imdeadpool/guardex` from `7.0.27` to `7.0.28` so the CLI help redesign can ship on a fresh npm version.
+- `gx --help` and `gx` (no args) now render commands as a grouped catalog (Setup & health / Branch workflow / Coordination / Agents & reports / Meta) with short group descriptions, so the top of the help screen shows the newcomer path instead of a flat 20-row list.
+- Added a three-step Quickstart block (`gx setup` → `gx branch start "<task>" "<agent>"` → `gx branch finish --via-pr --wait-for-merge --cleanup`) to both help surfaces so the intended install/setup sequence is visible before the full command reference.
+- Exposed `CLI_COMMAND_GROUPS` and `CLI_QUICKSTART_STEPS` from `src/context.js` (with `CLI_COMMAND_DESCRIPTIONS` derived from the grouped source of truth), giving future help tooling and integrations a structured way to iterate the catalog without re-parsing flat rows.
+
 ### v7.0.27
 - Bumped `@imdeadpool/guardex` from `7.0.26` to `7.0.27` so npm can publish a fresh version after `7.0.26` was already taken on the registry.
 - The shipped `agent-branch-start.sh` copies now keep the startup auto-transfer path alive under `set -o pipefail`, so Guardex can still restore moved changes back to the protected checkout when branch startup hits a later failure.

package/package.json

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

@@ -146,8 +146,10 @@ const {
   colorizeDoctorOutput,
   statusDot,
   printToolLogsSummary,
+  getInvokedCliName,
   usage,
   formatElapsedDuration,
+  startTransientSpinner,
   compactAutoFinishPathSegments,
   detectRecoverableAutoFinishConflict,
   printAutoFinishSummary,
@@ -889,6 +891,80 @@ function parseBooleanLike(raw) {
   return null;
 }
 
+function autoDoctorEnabledForCurrentSession() {
+  const explicit = parseBooleanLike(process.env.GUARDEX_AUTO_DOCTOR);
+  if (explicit != null) {
+    return explicit;
+  }
+  return isInteractiveTerminal();
+}
+
+function shouldAutoRunDoctorFromStatus(statusPayload) {
+  const repo = statusPayload?.repo || {};
+  return Boolean(
+    autoDoctorEnabledForCurrentSession()
+    && repo.inGitRepo
+    && repo.guardexEnabled !== false
+    && repo.serviceStatus === 'degraded'
+    && repo.scan
+    && Number(repo.scan.findings || 0) > 0,
+  );
+}
+
+function runCliSubprocessWithSpinner(args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const spinner = options.spinnerMessage
+      ? startTransientSpinner(options.spinnerMessage, {
+        prefix: options.spinnerPrefix || `[${TOOL_NAME}]`,
+      })
+      : { stop() {} };
+    const child = cp.spawn(process.execPath, [path.resolve(__filename), ...args], {
+      cwd: options.cwd || process.cwd(),
+      env: {
+        ...process.env,
+        GUARDEX_AUTO_DOCTOR: '0',
+      },
+      stdio: ['inherit', 'pipe', 'pipe'],
+    });
+
+    const stopSpinner = () => spinner.stop();
+    child.stdout.on('data', (chunk) => {
+      stopSpinner();
+      process.stdout.write(chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+      stopSpinner();
+      process.stderr.write(chunk);
+    });
+    child.on('error', (error) => {
+      stopSpinner();
+      reject(error);
+    });
+    child.on('close', (code) => {
+      stopSpinner();
+      resolve(typeof code === 'number' ? code : 1);
+    });
+  });
+}
+
+async function maybeAutoRunDoctorFromDefaultStatus(statusPayload) {
+  if (!shouldAutoRunDoctorFromStatus(statusPayload)) {
+    return false;
+  }
+
+  const target = statusPayload?.repo?.target || process.cwd();
+  console.log(`[${TOOL_NAME}] Auto-repair: repo safety is degraded. Running '${SHORT_TOOL_NAME} doctor --current' now.`);
+  process.exitCode = await runCliSubprocessWithSpinner(
+    ['doctor', '--target', target, '--current'],
+    {
+      cwd: target,
+      spinnerPrefix: `[${TOOL_NAME}] Auto-repair:`,
+      spinnerMessage: 'preparing doctor workspace',
+    },
+  );
+  return true;
+}
+
 function parseDotenvAssignmentValue(raw) {
   let value = String(raw || '').trim();
   if (!value) return '';
@@ -1672,12 +1748,62 @@ function setExitCodeFromScan(scan) {
   process.exitCode = 0;
 }
 
-function status(rawArgs) {
-  const options = parseCommonArgs(rawArgs, {
-    target: process.cwd(),
-    json: false,
-  });
+function printStatusRepairHint(scanResult) {
+  if (!scanResult || scanResult.guardexEnabled === false) {
+    return;
+  }
+  if (scanResult.errors === 0 && scanResult.warnings === 0) {
+    return;
+  }
+
+  const scanHint = scanResult.errors === 0
+    ? `review warning details with '${SHORT_TOOL_NAME} scan'`
+    : `inspect detailed findings with '${SHORT_TOOL_NAME} scan'`;
+  console.log(
+    `[${TOOL_NAME}] Quick fix: run '${SHORT_TOOL_NAME} doctor' to repair drift, or ${scanHint}.`,
+  );
+}
+
+function countAgentWorktrees(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return 0;
+  const relPaths = ['.omc/agent-worktrees', '.omx/agent-worktrees'];
+  let count = 0;
+  for (const rel of relPaths) {
+    try {
+      const entries = fs.readdirSync(path.join(repoRoot, rel), { withFileTypes: true });
+      count += entries.filter((entry) => entry.isDirectory()).length;
+    } catch (_err) {
+      // missing dir or permission error; not an active-agent signal
+    }
+  }
+  return count;
+}
+
+function deriveNextStepHint({ scanResult, worktreeCount, invoked, inGitRepo }) {
+  if (!inGitRepo) {
+    return `${invoked} setup --target <path-to-git-repo>   # initialize guardrails in a repo`;
+  }
+  if (!scanResult) {
+    return `${invoked} setup   # bootstrap repo guardrails`;
+  }
+  if (scanResult.guardexEnabled === false) {
+    return `set GUARDEX_ON=1 in .env   # re-enable guardrails, then '${invoked} doctor'`;
+  }
+  const branch = scanResult.branch || '';
+  if (branch.startsWith('agent/')) {
+    return `${invoked} branch finish --branch "${branch}" --via-pr --wait-for-merge --cleanup`;
+  }
+  if (worktreeCount > 0) {
+    const plural = worktreeCount === 1 ? 'worktree' : 'worktrees';
+    return `${invoked} finish --all   # ${worktreeCount} active agent ${plural}`;
+  }
+  if (scanResult.errors > 0 || scanResult.warnings > 0) {
+    return `${invoked} doctor   # repair drift`;
+  }
+  return `${invoked} branch start "<task>" "<agent-name>"   # start a sandboxed agent task`;
+}
 
+function collectServicesSnapshot() {
   const toolchain = toolchainModule.detectGlobalToolchainPackages();
   const npmServices = GLOBAL_TOOLCHAIN_PACKAGES.map((pkg) => {
     const service = toolchainModule.getGlobalToolchainService(pkg);
@@ -1701,18 +1827,103 @@ function status(rawArgs) {
   const localCompanionServices = toolchainModule.detectOptionalLocalCompanionTools().map((tool) => ({
     name: tool.name,
     displayName: tool.displayName || tool.name,
+    installCommand: tool.installCommand,
+    installArgs: Array.isArray(tool.installArgs) ? [...tool.installArgs] : [],
     status: tool.status,
   }));
   const requiredSystemTools = toolchainModule.detectRequiredSystemTools();
   const services = [
     ...npmServices,
-    ...localCompanionServices,
+    ...localCompanionServices.map((tool) => ({
+      name: tool.name,
+      displayName: tool.displayName,
+      status: tool.status,
+    })),
     ...requiredSystemTools.map((tool) => ({
       name: tool.name,
       displayName: tool.displayName || tool.name,
       status: tool.status,
     })),
   ];
+  return { toolchain, npmServices, localCompanionServices, requiredSystemTools, services };
+}
+
+function maybePromptInstallMissingCompanions(snapshot) {
+  if (envFlagIsTruthy(process.env.GUARDEX_SKIP_COMPANION_PROMPT)) {
+    return { handled: false, installed: false };
+  }
+  const interactive = Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY);
+  const autoApproval = toolchainModule.parseAutoApproval('GUARDEX_AUTO_COMPANION_APPROVAL');
+  if (!interactive && autoApproval == null) {
+    return { handled: false, installed: false };
+  }
+  if (!snapshot.toolchain.ok) {
+    return { handled: false, installed: false };
+  }
+
+  const missingPackages = snapshot.npmServices
+    .filter((service) => service.status !== 'active')
+    .map((service) => service.packageName);
+  const missingLocalTools = snapshot.localCompanionServices.filter((tool) => tool.status !== 'active');
+  if (missingPackages.length === 0 && missingLocalTools.length === 0) {
+    return { handled: false, installed: false };
+  }
+
+  const missingNames = [
+    ...missingPackages.map((pkg) => toolchainModule.formatGlobalToolchainServiceName(pkg)),
+    ...missingLocalTools.map((tool) => tool.displayName || tool.name),
+  ];
+  console.log(`[${TOOL_NAME}] Missing companion tools: ${missingNames.join(', ')}.`);
+
+  const promptText = toolchainModule.buildMissingCompanionInstallPrompt(missingPackages, missingLocalTools);
+  const approved = interactive
+    ? toolchainModule.promptYesNoStrict(promptText)
+    : autoApproval;
+
+  if (!approved) {
+    console.log(
+      `[${TOOL_NAME}] Skipped companion install. Set GUARDEX_SKIP_COMPANION_PROMPT=1 to silence this prompt, ` +
+      `or run '${getInvokedCliName()} setup --install-only' later to install manually.`,
+    );
+    return { handled: true, installed: false };
+  }
+
+  const result = toolchainModule.performCompanionInstall(missingPackages, missingLocalTools);
+  if (result.status === 'installed') {
+    console.log(
+      `[${TOOL_NAME}] ✅ Companion tools installed (${(result.packages || []).join(', ')}).`,
+    );
+    return { handled: true, installed: true };
+  }
+  if (result.status === 'failed') {
+    console.log(
+      `[${TOOL_NAME}] ⚠️ Companion install failed: ${result.reason}. ` +
+      `Retry with '${getInvokedCliName()} setup --install-only'.`,
+    );
+    return { handled: true, installed: false };
+  }
+  return { handled: true, installed: false };
+}
+
+function status(rawArgs) {
+  const { found: verboseFlag, remaining: afterVerbose } = extractFlag(rawArgs, '--verbose');
+  const options = parseCommonArgs(afterVerbose, {
+    target: process.cwd(),
+    json: false,
+  });
+  const forceCompact = envFlagIsTruthy(process.env.GUARDEX_COMPACT_STATUS);
+  const forceExpand = envFlagIsTruthy(process.env.GUARDEX_VERBOSE_STATUS) || verboseFlag;
+  const interactive = Boolean(process.stdout.isTTY);
+  const invokedBasename = getInvokedCliName();
+
+  let snapshot = collectServicesSnapshot();
+  if (!options.json) {
+    const result = maybePromptInstallMissingCompanions(snapshot);
+    if (result.installed) {
+      snapshot = collectServicesSnapshot();
+    }
+  }
+  let { toolchain, npmServices, localCompanionServices, requiredSystemTools, services } = snapshot;
 
   const targetPath = path.resolve(options.target);
   const inGitRepo = isGitRepo(targetPath);
@@ -1752,18 +1963,27 @@ function status(rawArgs) {
   if (options.json) {
     process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
     process.exitCode = 0;
-    return;
+    return payload;
   }
 
+  const allServicesActive = toolchain.ok && services.every((service) => service.status === 'active');
+  const compact = !forceExpand && (forceCompact || (interactive && allServicesActive));
+
   console.log(`[${TOOL_NAME}] CLI: ${payload.cli.runtime}`);
   if (!toolchain.ok) {
     console.log(`[${TOOL_NAME}] ⚠️ Could not detect global services: ${toolchain.error}`);
   }
 
-  console.log(`[${TOOL_NAME}] Global services:`);
-  for (const service of services) {
-    const serviceLabel = service.displayName || service.name;
-    console.log(`  - ${statusDot(service.status)} ${serviceLabel}: ${service.status}`);
+  if (compact) {
+    console.log(
+      `[${TOOL_NAME}] Global services: ${services.length}/${services.length} ${statusDot('active')} active`,
+    );
+  } else {
+    console.log(`[${TOOL_NAME}] Global services:`);
+    for (const service of services) {
+      const serviceLabel = service.displayName || service.name;
+      console.log(`  - ${statusDot(service.status)} ${serviceLabel}: ${service.status}`);
+    }
   }
   const inactiveOptionalCompanions = [...npmServices, ...localCompanionServices]
     .filter((service) => service.status !== 'active')
@@ -1799,8 +2019,16 @@ function status(rawArgs) {
     console.log(
       `[${TOOL_NAME}] Repo safety service: ${statusDot('inactive')} inactive (no git repository at target).`,
     );
+    const inactiveHint = deriveNextStepHint({
+      scanResult: null,
+      worktreeCount: 0,
+      invoked: invokedBasename,
+      inGitRepo,
+    });
+    console.log(`[${TOOL_NAME}] Next: ${inactiveHint}`);
+    printToolLogsSummary({ invokedBasename, compact });
     process.exitCode = 0;
-    return;
+    return payload;
   }
 
   if (scanResult.guardexEnabled === false) {
@@ -1809,9 +2037,23 @@ function status(rawArgs) {
     );
     console.log(`[${TOOL_NAME}] Repo: ${scanResult.repoRoot}`);
     console.log(`[${TOOL_NAME}] Branch: ${scanResult.branch}`);
-    printToolLogsSummary();
+    const worktreeCountDisabled = countAgentWorktrees(scanResult.repoRoot);
+    if (worktreeCountDisabled > 0) {
+      const plural = worktreeCountDisabled === 1 ? 'worktree' : 'worktrees';
+      console.log(
+        `[${TOOL_NAME}] ⚠ ${worktreeCountDisabled} active agent ${plural} under .omc/agent-worktrees or .omx/agent-worktrees.`,
+      );
+    }
+    const disabledHint = deriveNextStepHint({
+      scanResult,
+      worktreeCount: worktreeCountDisabled,
+      invoked: invokedBasename,
+      inGitRepo,
+    });
+    console.log(`[${TOOL_NAME}] Next: ${disabledHint}`);
+    printToolLogsSummary({ invokedBasename, compact });
     process.exitCode = 0;
-    return;
+    return payload;
   }
 
   if (scanResult.errors === 0 && scanResult.warnings === 0) {
@@ -1820,23 +2062,36 @@ function status(rawArgs) {
     console.log(
       `[${TOOL_NAME}] Repo safety service: ${statusDot('degraded')} degraded (${scanResult.warnings} warning(s)).`,
     );
-    console.log(`[${TOOL_NAME}] Run '${TOOL_NAME} scan' to review warning details.`);
   } else if (scanResult.warnings === 0) {
     console.log(
       `[${TOOL_NAME}] Repo safety service: ${statusDot('degraded')} degraded (${scanResult.errors} error(s)).`,
     );
-    console.log(`[${TOOL_NAME}] Run '${TOOL_NAME} scan' for detailed findings.`);
   } else {
     console.log(
       `[${TOOL_NAME}] Repo safety service: ${statusDot('degraded')} degraded (${scanResult.errors} error(s), ${scanResult.warnings} warning(s)).`,
     );
-    console.log(`[${TOOL_NAME}] Run '${TOOL_NAME} scan' for detailed findings.`);
   }
+  printStatusRepairHint(scanResult);
   console.log(`[${TOOL_NAME}] Repo: ${scanResult.repoRoot}`);
   console.log(`[${TOOL_NAME}] Branch: ${scanResult.branch}`);
-  printToolLogsSummary();
+  const worktreeCountActive = countAgentWorktrees(scanResult.repoRoot);
+  if (worktreeCountActive > 0) {
+    const plural = worktreeCountActive === 1 ? 'worktree' : 'worktrees';
+    console.log(
+      `[${TOOL_NAME}] ⚠ ${worktreeCountActive} active agent ${plural} → ${invokedBasename} finish --all`,
+    );
+  }
+  const activeHint = deriveNextStepHint({
+    scanResult,
+    worktreeCount: worktreeCountActive,
+    invoked: invokedBasename,
+    inGitRepo,
+  });
+  console.log(`[${TOOL_NAME}] Next: ${activeHint}`);
+  printToolLogsSummary({ invokedBasename, compact });
 
   process.exitCode = 0;
+  return payload;
 }
 
 function install(rawArgs) {
@@ -3246,13 +3501,14 @@ function protect(rawArgs) {
   throw new Error(`Unknown protect subcommand: ${subcommand}`);
 }
 
-function main() {
+async function main() {
   const args = process.argv.slice(2);
 
   if (args.length === 0) {
     toolchainModule.maybeSelfUpdateBeforeStatus();
     toolchainModule.maybeOpenSpecUpdateBeforeStatus();
-    status([]);
+    const statusPayload = status([]);
+    await maybeAutoRunDoctorFromDefaultStatus(statusPayload);
     return;
   }
 
@@ -3322,9 +3578,9 @@ function main() {
   throw new Error(`Unknown command: ${command}`);
 }
 
-function runFromBin() {
+async function runFromBin() {
   try {
-    main();
+    await main();
   } catch (error) {
     console.error(`[${TOOL_NAME}] ${error.message}`);
     process.exitCode = 1;
@@ -3332,7 +3588,7 @@ function runFromBin() {
 }
 
 if (require.main === module) {
-  runFromBin();
+  void runFromBin();
 }
 
 module.exports = {

package/src/context.js

@@ -363,27 +363,68 @@ const SUGGESTIBLE_COMMANDS = [
   'print-agents-snippet',
   'release',
 ];
-const CLI_COMMAND_DESCRIPTIONS = [
-  ['status', 'Show GitGuardex CLI + service health without modifying files'],
-  ['setup', 'Install, repair, and verify guardrails (flags: --repair, --install-only, --target, --current)'],
-  ['doctor', 'Repair drift + verify (flags: --target, --current; auto-sandboxes on protected main)'],
-  ['branch', 'CLI-owned branch workflow surface (start/finish/merge)'],
-  ['locks', 'CLI-owned file lock surface (claim/allow-delete/release/status/validate)'],
-  ['worktree', 'CLI-owned worktree cleanup surface (prune)'],
-  ['hook', 'Hook dispatch/install surface used by managed shims'],
-  ['migrate', 'Convert legacy repo-local installs to the zero-copy CLI-owned surface'],
-  ['install-agent-skills', 'Install Guardex Codex/Claude skills into the user home'],
-  ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
-  ['merge', 'Create/reuse an integration lane and merge overlapping agent branches'],
-  ['sync', 'Sync agent branches with origin/<base>'],
-  ['finish', 'Commit + PR + merge completed agent branches (--all, --branch)'],
-  ['cleanup', 'Prune merged/stale agent branches and worktrees'],
-  ['release', 'Create or update the current GitHub release with README-generated notes'],
-  ['agents', 'Start/stop repo-scoped review + cleanup bots'],
-  ['prompt', 'Print AI setup checklist or named slices (--exec, --part, --list-parts, --snippet)'],
-  ['report', 'Security/safety reports (e.g. OpenSSF scorecard, session severity)'],
-  ['help', 'Show this help output'],
-  ['version', 'Print GitGuardex version'],
+// CLI_COMMAND_GROUPS is the grouped source of truth the `gx --help` /
+// `gx` no-args renderer uses. Each group is ordered roughly by how often a
+// user reaches for it so the help screen answers "what do I run first?"
+// before "what else can this do?". CLI_COMMAND_DESCRIPTIONS preserves the
+// flat export for callers that still want the ungrouped list.
+const CLI_COMMAND_GROUPS = [
+  {
+    label: 'Setup & health',
+    description: 'Install, repair, and check a repo. Run these first on a new clone.',
+    commands: [
+      ['setup', 'Install, repair, and verify guardrails (flags: --repair, --install-only, --target, --current)'],
+      ['doctor', 'Repair drift + verify (flags: --target, --current; auto-sandboxes on protected main)'],
+      ['status', 'Show GitGuardex CLI + service health without modifying files'],
+      ['migrate', 'Convert legacy repo-local installs to the zero-copy CLI-owned surface'],
+    ],
+  },
+  {
+    label: 'Branch workflow',
+    description: 'The sandbox → commit → PR → merge loop for agent-owned branches.',
+    commands: [
+      ['branch', 'CLI-owned branch workflow surface (start/finish/merge)'],
+      ['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>'],
+      ['cleanup', 'Prune merged/stale agent branches and worktrees'],
+    ],
+  },
+  {
+    label: 'Coordination',
+    description: 'File locks, worktrees, hooks, and protected-branch policy.',
+    commands: [
+      ['locks', 'CLI-owned file lock surface (claim/allow-delete/release/status/validate)'],
+      ['worktree', 'CLI-owned worktree cleanup surface (prune)'],
+      ['hook', 'Hook dispatch/install surface used by managed shims'],
+      ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
+    ],
+  },
+  {
+    label: 'Agents & reports',
+    description: 'Review / cleanup bots, AI setup prompts, and safety reports.',
+    commands: [
+      ['agents', 'Start/stop repo-scoped review + cleanup bots'],
+      ['install-agent-skills', 'Install Guardex Codex/Claude skills into the user home'],
+      ['prompt', 'Print AI setup checklist or named slices (--exec, --part, --list-parts, --snippet)'],
+      ['report', 'Security/safety reports (e.g. OpenSSF scorecard, session severity)'],
+      ['release', 'Create or update the current GitHub release with README-generated notes'],
+    ],
+  },
+  {
+    label: 'Meta',
+    description: 'Version + help.',
+    commands: [
+      ['help', 'Show this help output'],
+      ['version', 'Print GitGuardex version'],
+    ],
+  },
+];
+const CLI_COMMAND_DESCRIPTIONS = CLI_COMMAND_GROUPS.flatMap((group) => group.commands);
+const CLI_QUICKSTART_STEPS = [
+  'gx setup',
+  'gx branch start "<task>" "<agent>"',
+  'gx branch finish --via-pr --wait-for-merge --cleanup',
 ];
 const DEPRECATED_COMMAND_ALIASES = new Map([
   ['init', { target: 'setup', hint: 'gx setup' }],
@@ -686,6 +727,8 @@ module.exports = {
   COMMAND_TYPO_ALIASES,
   SUGGESTIBLE_COMMANDS,
   CLI_COMMAND_DESCRIPTIONS,
+  CLI_COMMAND_GROUPS,
+  CLI_QUICKSTART_STEPS,
   DEPRECATED_COMMAND_ALIASES,
   AGENT_BOT_DESCRIPTIONS,
   DOCTOR_AUTO_FINISH_DETAIL_LIMIT,

package/src/doctor/index.js

@@ -31,6 +31,7 @@ const {
 } = require('../sandbox');
 const { ensureOmxScaffold, configureHooks } = require('../scaffold');
 const { detectRecoverableAutoFinishConflict, printAutoFinishSummary } = require('../output');
+const { autoCommitWorktreeForFinish } = require('../finish');
 
 /**
  * @typedef {Object} SandboxMetadata
@@ -887,23 +888,25 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
     return summary;
   }
 
-  if (!hasOriginRemote(repoRoot)) {
-    summary.enabled = false;
-    summary.details.push('Skipped auto-finish sweep (origin remote missing).');
-    return summary;
-  }
+  const originAvailable = hasOriginRemote(repoRoot);
   const explicitGhBin = Boolean(String(process.env.GUARDEX_GH_BIN || '').trim());
-  if (!explicitGhBin && !originRemoteLooksLikeGithub(repoRoot)) {
-    summary.enabled = false;
-    summary.details.push('Skipped auto-finish sweep (origin remote is not GitHub).');
-    return summary;
-  }
-
   const ghBin = process.env.GUARDEX_GH_BIN || 'gh';
-  if (run(ghBin, ['--version']).status !== 0) {
-    summary.enabled = false;
-    summary.details.push(`Skipped auto-finish sweep (${ghBin} not available).`);
-    return summary;
+  const ghAvailable =
+    originAvailable &&
+    (explicitGhBin || originRemoteLooksLikeGithub(repoRoot)) &&
+    run(ghBin, ['--version']).status === 0;
+
+  let fallbackMode = '';
+  if (!originAvailable) {
+    fallbackMode = 'local';
+    summary.details.push('origin remote missing; falling back to local direct merge (no push, no PR).');
+  } else if (!ghAvailable) {
+    fallbackMode = 'direct';
+    if (!explicitGhBin && !originRemoteLooksLikeGithub(repoRoot)) {
+      summary.details.push('origin remote is not GitHub; falling back to direct merge + push.');
+    } else {
+      summary.details.push(`${ghBin} not available; falling back to direct merge + push.`);
+    }
   }
 
   const branchWorktrees = mapWorktreePathsByBranch(repoRoot);
@@ -936,16 +939,29 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
       continue;
     }
 
+    const branchWorktree = branchWorktrees.get(branch) || '';
+    if (branchWorktree && hasSignificantWorkingTreeChanges(branchWorktree)) {
+      try {
+        const commitResult = autoCommitWorktreeForFinish(repoRoot, branchWorktree, branch, {});
+        if (commitResult.committed) {
+          counts = aheadBehind(repoRoot, branch, baseBranch);
+        }
+      } catch (error) {
+        summary.failed += 1;
+        summary.details.push(`[fail] ${branch}: auto-commit failed (${error.message}).`);
+        continue;
+      }
+    }
+
     if (counts.ahead <= 0) {
       summary.skipped += 1;
       summary.details.push(`[skip] ${branch}: already merged into ${baseBranch}.`);
       continue;
     }
 
-    const branchWorktree = branchWorktrees.get(branch) || '';
     if (branchWorktree && hasSignificantWorkingTreeChanges(branchWorktree)) {
       summary.skipped += 1;
-      summary.details.push(`[skip] ${branch}: dirty worktree (${branchWorktree}).`);
+      summary.details.push(`[skip] ${branch}: dirty worktree after auto-commit (${branchWorktree}).`);
       continue;
     }
 
@@ -955,10 +971,16 @@ function autoFinishReadyAgentBranches(repoRoot, options = {}) {
       branch,
       '--base',
       baseBranch,
-      '--via-pr',
-      waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge',
-      '--cleanup',
     ];
+    if (fallbackMode === 'local') {
+      finishArgs.push('--direct-only', '--no-push');
+    } else if (fallbackMode === 'direct') {
+      finishArgs.push('--direct-only');
+    } else {
+      finishArgs.push('--via-pr');
+    }
+    finishArgs.push(waitForMerge ? '--wait-for-merge' : '--no-wait-for-merge');
+    finishArgs.push('--cleanup');
     const finishResult = runPackageAsset('branchFinish', finishArgs, { cwd: repoRoot });
     const combinedOutput = [finishResult.stdout || '', finishResult.stderr || ''].join('\n').trim();
 

package/src/finish/index.js

@@ -521,4 +521,5 @@ module.exports = {
   merge,
   finish,
   sync,
+  autoCommitWorktreeForFinish,
 };

package/src/output/index.js

@@ -6,6 +6,8 @@ const {
   LEGACY_NAMES,
   GUARDEX_REPO_TOGGLE_ENV,
   CLI_COMMAND_DESCRIPTIONS,
+  CLI_COMMAND_GROUPS,
+  CLI_QUICKSTART_STEPS,
   AGENT_BOT_DESCRIPTIONS,
   DOCTOR_AUTO_FINISH_DETAIL_LIMIT,
   DOCTOR_AUTO_FINISH_BRANCH_LABEL_MAX,
@@ -166,6 +168,41 @@ function commandCatalogLines(indent = '  ') {
   );
 }
 
+// groupedCommandCatalogLines renders CLI_COMMAND_GROUPS as a nested list with
+// group headers separated by blank lines. It accepts an optional `colorize`
+// callback so the caller can decide whether to decorate the group label (tty
+// mode) or leave it plain (non-tty / NO_COLOR). Returns an array of lines;
+// `null` entries mean "emit a blank line" so tree renderers can echo pipe
+// characters on the separator rows.
+function groupedCommandCatalogLines(indent = '  ', options = {}) {
+  const colorizeLabel = typeof options.colorizeLabel === 'function'
+    ? options.colorizeLabel
+    : (text) => text;
+  const maxCommandLength = CLI_COMMAND_DESCRIPTIONS.reduce(
+    (max, [command]) => Math.max(max, command.length),
+    0,
+  );
+  const lines = [];
+  for (let groupIndex = 0; groupIndex < CLI_COMMAND_GROUPS.length; groupIndex += 1) {
+    const group = CLI_COMMAND_GROUPS[groupIndex];
+    const header = group.description
+      ? `${colorizeLabel(group.label)} — ${group.description}`
+      : colorizeLabel(group.label);
+    lines.push(`${indent}${header}`);
+    for (const [command, description] of group.commands) {
+      lines.push(`${indent}  ${command.padEnd(maxCommandLength + 2)}${description}`);
+    }
+    if (groupIndex < CLI_COMMAND_GROUPS.length - 1) {
+      lines.push(null);
+    }
+  }
+  return lines;
+}
+
+function quickstartLines(indent = '  ') {
+  return CLI_QUICKSTART_STEPS.map((step, index) => `${indent}${index + 1}. ${step}`);
+}
+
 function agentBotCatalogLines(indent = '  ') {
   const maxCommandLength = AGENT_BOT_DESCRIPTIONS.reduce(
     (max, [command]) => Math.max(max, command.length),
@@ -182,19 +219,43 @@ function repoToggleLines(indent = '  ') {
   ];
 }
 
-function printToolLogsSummary() {
-  const usageLine = `    $ ${SHORT_TOOL_NAME} <command> [options]`;
-  const commandDetails = commandCatalogLines('    ');
+const KNOWN_CLI_BASENAMES = new Set(['gx', 'gitguardex', 'guardex']);
+
+function getInvokedCliName() {
+  const raw = path.basename(String(process.argv[1] || '')).replace(/\.js$/, '');
+  if (!KNOWN_CLI_BASENAMES.has(raw)) {
+    return SHORT_TOOL_NAME;
+  }
+  return raw;
+}
+
+function printToolLogsSummary(options = {}) {
+  const invoked = options.invokedBasename || getInvokedCliName();
+  const compact = Boolean(options.compact);
+
+  if (compact) {
+    const helpLine = `Try '${invoked} help' for commands, or '${invoked} status --verbose' for full service details.`;
+    console.log(`[${TOOL_NAME}] ${colorize(helpLine, '2')}`);
+    return;
+  }
+
+  const usageLine = `    $ ${invoked} <command> [options]`;
+  const quickstartDetails = quickstartLines('    ');
   const agentBotDetails = agentBotCatalogLines('    ');
   const repoToggleDetails = repoToggleLines('    ');
 
   if (!supportsAnsiColors()) {
-    console.log(`${TOOL_NAME}-tools logs:`);
+    const commandDetails = groupedCommandCatalogLines('    ');
+    console.log(`${invoked} help:`);
     console.log('  USAGE');
     console.log(usageLine);
+    console.log('  QUICKSTART');
+    for (const line of quickstartDetails) {
+      console.log(line);
+    }
     console.log('  COMMANDS');
     for (const line of commandDetails) {
-      console.log(line);
+      console.log(line ?? '');
     }
     console.log('  AGENT BOT');
     for (const line of agentBotDetails) {
@@ -204,24 +265,33 @@ function printToolLogsSummary() {
     for (const line of repoToggleDetails) {
       console.log(line);
     }
+    console.log(`  Try '${invoked} doctor' for one-step repair + verification.`);
     return;
   }
 
-  const title = colorize(`${TOOL_NAME}-tools logs`, '1;36');
+  const title = colorize(`${invoked} help`, '1;36');
   const usageHeader = colorize('USAGE', '1');
+  const quickstartHeader = colorize('QUICKSTART', '1');
   const commandsHeader = colorize('COMMANDS', '1');
   const agentBotHeader = colorize('AGENT BOT', '1');
   const repoToggleHeader = colorize('REPO TOGGLE', '1');
   const pipe = colorize('│', '90');
   const tee = colorize('├', '90');
   const corner = colorize('└', '90');
+  const commandDetails = groupedCommandCatalogLines('    ', {
+    colorizeLabel: (text) => colorize(text, '1;36'),
+  });
 
   console.log(`${title}:`);
   console.log(`  ${tee}─ ${usageHeader}`);
   console.log(`  ${pipe}${usageLine}`);
+  console.log(`  ${tee}─ ${quickstartHeader}`);
+  for (const line of quickstartDetails) {
+    console.log(`  ${pipe}${line.slice(2)}`);
+  }
   console.log(`  ${tee}─ ${commandsHeader}`);
   for (const line of commandDetails) {
-    if (!line) {
+    if (line == null) {
       console.log(`  ${pipe}`);
       continue;
     }
@@ -243,11 +313,18 @@ function printToolLogsSummary() {
     }
     console.log(`  ${pipe}${line.slice(2)}`);
   }
-  console.log(`  ${corner}─ ${colorize(`Try '${TOOL_NAME} doctor' for one-step repair + verification.`, '2')}`);
+  console.log(`  ${corner}─ ${colorize(`Try '${invoked} doctor' for one-step repair + verification.`, '2')}`);
 }
 
 function usage(options = {}) {
   const { outsideGitRepo = false } = options;
+  const invoked = options.invokedBasename || getInvokedCliName();
+
+  const groupedCommandLines = groupedCommandCatalogLines('  ', {
+    colorizeLabel: (text) => colorize(text, '1;36'),
+  })
+    .map((line) => (line == null ? '' : line))
+    .join('\n');
 
   console.log(`A command-line tool that sets up hardened multi-agent safety for git repositories.
 
@@ -255,10 +332,13 @@ VERSION
   ${runtimeVersion()}
 
 USAGE
-  $ ${SHORT_TOOL_NAME} <command> [options]
+  $ ${invoked} <command> [options]
+
+QUICKSTART
+${quickstartLines().join('\n')}
 
 COMMANDS
-${commandCatalogLines().join('\n')}
+${groupedCommandLines}
 
 AGENT BOT
 ${agentBotCatalogLines().join('\n')}
@@ -267,19 +347,20 @@ REPO TOGGLE
 ${repoToggleLines().join('\n')}
 
 NOTES
-  - No command = ${SHORT_TOOL_NAME} status. ${SHORT_TOOL_NAME} init is an alias of ${SHORT_TOOL_NAME} setup.
+  - No command = ${invoked} status (compact in a TTY; pass --verbose for full services + help tree).
+  - ${invoked} init is an alias of ${invoked} setup.
   - Global installs need Y/N approval; GitHub CLI (gh) is required for PR automation.
-  - Target another repo: ${SHORT_TOOL_NAME} <cmd> --target <repo-path>.
+  - Target another repo: ${invoked} <cmd> --target <repo-path>.
   - On protected main, setup/install/fix/doctor auto-sandbox via agent branch + PR flow.
-  - Run '${SHORT_TOOL_NAME} cleanup' to prune merged agent branches/worktrees.
+  - Run '${invoked} cleanup' to prune merged agent branches/worktrees.
   - Legacy aliases: ${LEGACY_NAMES.join(', ')}.`);
 
   if (outsideGitRepo) {
     console.log(`
 [${TOOL_NAME}] No git repository detected in current directory.
 [${TOOL_NAME}] Start from a repo root, or pass an explicit target:
-  ${TOOL_NAME} setup --target <path-to-git-repo>
-  ${TOOL_NAME} doctor --target <path-to-git-repo>`);
+  ${invoked} setup --target <path-to-git-repo>
+  ${invoked} doctor --target <path-to-git-repo>`);
   }
 }
 
@@ -294,6 +375,59 @@ function formatElapsedDuration(ms) {
   return `${Math.round(durationMs / 1000)}s`;
 }
 
+function startTransientSpinner(message, options = {}) {
+  const stream = options.stream || process.stdout;
+  if (!stream || !stream.isTTY || typeof stream.write !== 'function') {
+    return {
+      stop() {},
+    };
+  }
+
+  const frames = supportsAnsiColors()
+    ? ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+    : ['-', '\\', '|', '/'];
+  const intervalMs = Number.isFinite(options.intervalMs) ? Math.max(60, options.intervalMs) : 80;
+  const prefix = String(options.prefix || `[${TOOL_NAME}]`).trim();
+  const text = String(message || '').trim();
+  let frameIndex = 0;
+  let stopped = false;
+
+  const render = () => {
+    const frame = frames[frameIndex % frames.length];
+    frameIndex += 1;
+    const indicator = supportsAnsiColors() ? colorize(frame, '36') : frame;
+    stream.write(`\r${prefix} ${indicator} ${text}`);
+  };
+
+  const clear = () => {
+    stream.write('\r');
+    if (typeof stream.clearLine === 'function') {
+      stream.clearLine(0);
+    }
+    if (typeof stream.cursorTo === 'function') {
+      stream.cursorTo(0);
+    }
+  };
+
+  render();
+  const timer = setInterval(render, intervalMs);
+  if (typeof timer.unref === 'function') {
+    timer.unref();
+  }
+
+  return {
+    stop(finalLine = '') {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      clear();
+      if (finalLine) {
+        stream.write(`${finalLine}\n`);
+      }
+    },
+  };
+}
+
 function truncateMiddle(value, maxLength) {
   const text = String(value || '');
   const limit = Number.isFinite(maxLength) ? Math.max(4, maxLength) : 0;
@@ -454,8 +588,10 @@ module.exports = {
   agentBotCatalogLines,
   repoToggleLines,
   printToolLogsSummary,
+  getInvokedCliName,
   usage,
   formatElapsedDuration,
+  startTransientSpinner,
   truncateMiddle,
   truncateTail,
   compactAutoFinishPathSegments,

package/src/toolchain/index.js

@@ -545,6 +545,10 @@ function installGlobalToolchain(options) {
     };
   }
 
+  return performCompanionInstall(missingPackages, missingLocalTools);
+}
+
+function performCompanionInstall(missingPackages, missingLocalTools) {
   const installed = [];
   if (missingPackages.length > 0) {
     console.log(
@@ -593,6 +597,7 @@ module.exports = {
   formatGlobalToolchainServiceName,
   describeMissingGlobalDependencyWarnings,
   describeCompanionInstallCommands,
+  buildMissingCompanionInstallPrompt,
   detectGlobalToolchainPackages,
   detectRequiredSystemTools,
   detectOptionalLocalCompanionTools,
@@ -600,4 +605,5 @@ module.exports = {
   maybeSelfUpdateBeforeStatus,
   maybeOpenSpecUpdateBeforeStatus,
   installGlobalToolchain,
+  performCompanionInstall,
 };

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

@@ -389,30 +389,45 @@ if [[ "$MERGE_MODE" == "pr" && "$PUSH_ENABLED" -eq 1 ]]; then
 fi
 
 if [[ "$should_create_integration_helper" -eq 1 ]]; then
-  integration_stamp="$(date +%Y%m%d-%H%M%S)"
-  integration_worktree_base="${temp_worktree_root}/__integrate-${BASE_BRANCH//\//__}-${integration_stamp}"
-  integration_branch_base="__agent_integrate_${BASE_BRANCH//\//_}_$(date +%Y%m%d_%H%M%S)"
-  integration_worktree="$integration_worktree_base"
-  integration_branch="$integration_branch_base"
-  integration_suffix=1
-  while [[ -e "$integration_worktree" ]] || git -C "$repo_root" show-ref --verify --quiet "refs/heads/${integration_branch}"; do
-    integration_worktree="${integration_worktree_base}-${integration_suffix}"
-    integration_branch="${integration_branch_base}_${integration_suffix}"
-    integration_suffix=$((integration_suffix + 1))
-  done
-  mkdir -p "$(dirname "$integration_worktree")"
+  existing_base_worktree=""
+  if [[ "$PUSH_ENABLED" -eq 0 ]]; then
+    existing_base_worktree="$(get_worktree_for_branch "$BASE_BRANCH")"
+  fi
 
-  git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null
-  git -C "$integration_worktree" checkout -b "$integration_branch" >/dev/null
+  if [[ -n "$existing_base_worktree" ]] && is_clean_worktree "$existing_base_worktree"; then
+    if ! git -C "$existing_base_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
+      echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
+      git -C "$existing_base_worktree" merge --abort >/dev/null 2>&1 || true
+      exit 1
+    fi
+    merge_completed=1
+    merge_status="direct"
+  else
+    integration_stamp="$(date +%Y%m%d-%H%M%S)"
+    integration_worktree_base="${temp_worktree_root}/__integrate-${BASE_BRANCH//\//__}-${integration_stamp}"
+    integration_branch_base="__agent_integrate_${BASE_BRANCH//\//_}_$(date +%Y%m%d_%H%M%S)"
+    integration_worktree="$integration_worktree_base"
+    integration_branch="$integration_branch_base"
+    integration_suffix=1
+    while [[ -e "$integration_worktree" ]] || git -C "$repo_root" show-ref --verify --quiet "refs/heads/${integration_branch}"; do
+      integration_worktree="${integration_worktree_base}-${integration_suffix}"
+      integration_branch="${integration_branch_base}_${integration_suffix}"
+      integration_suffix=$((integration_suffix + 1))
+    done
+    mkdir -p "$(dirname "$integration_worktree")"
+
+    git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null
+    git -C "$integration_worktree" checkout -b "$integration_branch" >/dev/null
+
+    if ! git -C "$integration_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
+      echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
+      git -C "$integration_worktree" merge --abort >/dev/null 2>&1 || true
+      exit 1
+    fi
 
-  if ! git -C "$integration_worktree" merge --no-ff --no-edit "$SOURCE_BRANCH"; then
-    echo "[agent-branch-finish] Merge conflict detected while merging '${SOURCE_BRANCH}' into '${BASE_BRANCH}'." >&2
-    git -C "$integration_worktree" merge --abort >/dev/null 2>&1 || true
-    exit 1
+    merge_completed=1
+    merge_status="direct"
   fi
-
-  merge_completed=1
-  merge_status="direct"
 fi
 
 is_local_branch_delete_error() {

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

@@ -340,16 +340,30 @@ resolve_openspec_capability_slug() {
   sanitize_slug "$task_slug" "general-behavior"
 }
 
+resolve_repo_prefix() {
+  local root
+  root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+  basename "$root"
+}
+
 resolve_worktree_leaf() {
   local branch_name="$1"
   local agent_slug="$2"
   local masterplan_label=""
   local branch_leaf=""
+  local repo_prefix
+  repo_prefix="$(resolve_repo_prefix)"
 
   masterplan_label="$(resolve_openspec_masterplan_label)"
   if [[ -n "$masterplan_label" ]] && [[ "$branch_name" == "agent/${agent_slug}/"* ]]; then
     branch_leaf="${branch_name#agent/${agent_slug}/}"
-    printf 'agent__%s__%s__%s' "$agent_slug" "$masterplan_label" "$branch_leaf"
+    printf '%s__%s__%s__%s' "$repo_prefix" "$agent_slug" "$masterplan_label" "$branch_leaf"
+    return 0
+  fi
+
+  if [[ "$branch_name" == agent/*/* ]]; then
+    local without_agent="${branch_name#agent/}"
+    printf '%s__%s' "$repo_prefix" "${without_agent//\//__}"
     return 0
   fi
 

package/templates/scripts/codex-agent.sh

@@ -372,17 +372,32 @@ resolve_openspec_capability_slug() {
   sanitize_slug "$task_slug" "general-behavior"
 }
 
+resolve_repo_prefix() {
+  local root
+  root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+  basename "$root"
+}
+
 resolve_worktree_leaf() {
   local branch_name="$1"
   local masterplan_label=""
   local branch_role=""
   local branch_leaf=""
+  local repo_prefix
+  repo_prefix="$(resolve_repo_prefix)"
 
   masterplan_label="$(resolve_openspec_masterplan_label)"
   if [[ -n "$masterplan_label" ]] && [[ "$branch_name" =~ ^agent/([^/]+)/(.+)$ ]]; then
     branch_role="${BASH_REMATCH[1]}"
     branch_leaf="${BASH_REMATCH[2]}"
-    printf 'agent__%s__%s__%s' "$branch_role" "$masterplan_label" "$branch_leaf"
+    printf '%s__%s__%s__%s' "$repo_prefix" "$branch_role" "$masterplan_label" "$branch_leaf"
+    return 0
+  fi
+
+  if [[ "$branch_name" =~ ^agent/([^/]+)/(.+)$ ]]; then
+    branch_role="${BASH_REMATCH[1]}"
+    branch_leaf="${BASH_REMATCH[2]}"
+    printf '%s__%s__%s' "$repo_prefix" "$branch_role" "$branch_leaf"
     return 0
   fi
 

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

@@ -56,6 +56,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: 'idle', label: 'THINKING' },
   { kind: 'stalled', label: 'STALLED' },
   { kind: 'dead', label: 'DEAD' },
@@ -63,6 +64,7 @@ const SESSION_ACTIVITY_GROUPS = [
 const SESSION_ACTIVITY_ICON_IDS = {
   blocked: 'warning',
   working: 'loading~spin',
+  finished: 'pass-filled',
   idle: 'comment-discussion',
   stalled: 'clock',
   dead: 'error',
@@ -108,6 +110,10 @@ function iconColorId(iconId) {
       return 'terminal.ansiCyan';
     case 'list-tree':
       return 'terminal.ansiBlue';
+    case 'pass-filled':
+    case 'pass':
+    case 'check':
+      return 'testing.iconPassed';
     default:
       return '';
   }
@@ -468,9 +474,15 @@ function agentBadgeFromBranch(branch) {
 
 function buildActiveAgentsStatusSummary(summary) {
   const workingCount = summary?.workingCount || 0;
+  const finishedCount = summary?.finishedCount || 0;
   const idleCount = summary?.idleCount || 0;
-  if (workingCount > 0 || idleCount > 0) {
-    return `$(git-branch) ${workingCount} working · ${idleCount} idle`;
+  if (workingCount > 0 || finishedCount > 0 || idleCount > 0) {
+    const parts = [`${workingCount} working`];
+    if (finishedCount > 0) {
+      parts.push(`${finishedCount} finished`);
+    }
+    parts.push(`${idleCount} idle`);
+    return `$(git-branch) ${parts.join(' · ')}`;
   }
   return `$(git-branch) ${formatCountLabel(summary?.sessionCount || 0, 'tracked session')}`;
 }
@@ -490,6 +502,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?.idleCount || 0, 'idle session'),
     formatCountLabel(summary?.unassignedChangeCount || 0, 'unassigned change'),
     formatCountLabel(summary?.lockedFileCount || 0, 'locked file'),
@@ -534,6 +547,10 @@ function countWorkingSessions(sessions) {
   )).length;
 }
 
+function countFinishedSessions(sessions) {
+  return sessions.filter((session) => session.activityKind === 'finished').length;
+}
+
 function countIdleSessions(sessions) {
   return sessions.filter((session) => (
     session.activityKind === 'idle' || session.activityKind === 'stalled'
@@ -571,6 +588,9 @@ function sessionFreshnessLabel(session, now = Date.now()) {
   if (session.activityKind === 'blocked') {
     return 'Needs attention';
   }
+  if (session.activityKind === 'finished') {
+    return 'Finished';
+  }
   if (session.activityKind === 'stalled') {
     return 'Possibly stale';
   }
@@ -598,6 +618,8 @@ function sessionStatusLabel(session) {
       return 'Blocked';
     case 'working':
       return 'Working';
+    case 'finished':
+      return 'Finished';
     case 'idle':
       return 'Idle';
     case 'stalled':
@@ -804,6 +826,7 @@ function buildWorktreeBranchDescription(sessions) {
 function buildOverviewDescription(summary) {
   return [
     formatCountLabel(summary?.workingCount || 0, 'working agent'),
+    formatCountLabel(summary?.finishedCount || 0, 'finished agent'),
     formatCountLabel(summary?.idleCount || 0, 'idle agent'),
     formatCountLabel(summary?.unassignedChangeCount || 0, 'unassigned change'),
     formatCountLabel(summary?.lockedFileCount || 0, 'locked file'),
@@ -923,6 +946,9 @@ function workingSessionSortKey(session) {
   if (session.deltaLabel === 'New') {
     return 3;
   }
+  if (session.activityKind === 'finished') {
+    return 5;
+  }
   return 4;
 }
 
@@ -2490,6 +2516,7 @@ function buildRepoOverview(sessions, unassignedChanges, lockEntries) {
   return {
     sessionCount: sessions.length,
     workingCount: countWorkingSessions(sessions),
+    finishedCount: countFinishedSessions(sessions),
     idleCount: countIdleSessions(sessions),
     unassignedChangeCount: (unassignedChanges || []).length,
     lockedFileCount: Array.isArray(lockEntries) ? lockEntries.length : 0,
@@ -2860,6 +2887,7 @@ class ActiveAgentsProvider {
     this.viewSummary = {
       sessionCount: 0,
       workingCount: 0,
+      finishedCount: 0,
       idleCount: 0,
       unassignedChangeCount: 0,
       lockedFileCount: 0,
@@ -2878,6 +2906,7 @@ class ActiveAgentsProvider {
     this.updateViewState({
       sessionCount: 0,
       workingCount: 0,
+      finishedCount: 0,
       idleCount: 0,
       unassignedChangeCount: 0,
       lockedFileCount: 0,
@@ -3000,6 +3029,10 @@ class ActiveAgentsProvider {
     const summary = {
       sessionCount: repoEntries.reduce((total, entry) => total + entry.sessions.length, 0),
       workingCount: repoEntries.reduce((total, entry) => total + entry.overview.workingCount, 0),
+      finishedCount: repoEntries.reduce(
+        (total, entry) => total + (entry.overview.finishedCount || 0),
+        0,
+      ),
       idleCount: repoEntries.reduce((total, entry) => total + entry.overview.idleCount, 0),
       unassignedChangeCount: repoEntries.reduce(
         (total, entry) => total + entry.overview.unassignedChangeCount,
@@ -3049,6 +3082,7 @@ class ActiveAgentsProvider {
           }),
         ], {
           description: '1',
+          collapsedState: vscode.TreeItemCollapsibleState.Collapsed,
         }),
       ];
 
@@ -3056,6 +3090,7 @@ class ActiveAgentsProvider {
       if (workingNowItems.length > 0) {
         sectionItems.push(new SectionItem('Working now', workingNowItems, {
           description: String(workingNowItems.length),
+          collapsedState: vscode.TreeItemCollapsibleState.Collapsed,
           iconId: 'loading~spin',
         }));
       }
@@ -3096,7 +3131,7 @@ class ActiveAgentsProvider {
       if (advancedItems.length > 0) {
         sectionItems.push(new SectionItem('Advanced details', advancedItems, {
           description: String(advancedItems.length),
-          collapsedState: vscode.TreeItemCollapsibleState.Collapsed,
+          collapsedState: vscode.TreeItemCollapsibleState.Expanded,
           iconId: 'list-tree',
         }));
       }

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": "recodeee",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "license": "MIT",
   "icon": "icon.png",
   "engines": {

package/templates/vscode/guardex-active-agents/session-schema.js

@@ -700,17 +700,35 @@ function deriveSessionActivity(session, options = {}) {
       .filter(Boolean))]
       .sort((left, right) => left.localeCompare(right));
 
+    const workingLatestFileActivityMs = deriveLatestWorktreeFileActivity(session.worktreePath, {
+      now,
+      useCache: options.useCache,
+    });
+    const workingLastFileActivityAt = Number.isFinite(workingLatestFileActivityMs)
+      ? new Date(workingLatestFileActivityMs).toISOString()
+      : '';
+    const workingLastFileActivityLabel = workingLastFileActivityAt
+      ? formatElapsedFrom(workingLastFileActivityAt, now)
+      : '';
+    const workingFileActivityAgeMs = Number.isFinite(workingLatestFileActivityMs)
+      ? Math.max(0, now - workingLatestFileActivityMs)
+      : null;
+    const isFinishedUncommitted = workingFileActivityAgeMs !== null
+      && workingFileActivityAgeMs > IDLE_ACTIVITY_WINDOW_MS;
+
     return {
-      activityKind: 'working',
-      activityLabel: 'working',
+      activityKind: isFinishedUncommitted ? 'finished' : 'working',
+      activityLabel: isFinishedUncommitted ? 'finished' : 'working',
       activityCountLabel: formatFileCount(worktreeChangedPaths.length),
-      activitySummary: previewChangedPaths(worktreeChangedPaths),
+      activitySummary: isFinishedUncommitted && workingLastFileActivityLabel
+        ? `${previewChangedPaths(worktreeChangedPaths)} · idle ${workingLastFileActivityLabel}`
+        : previewChangedPaths(worktreeChangedPaths),
       changeCount: worktreeChangedPaths.length,
       changedPaths,
       worktreeChangedPaths: worktreeRelativePaths,
       pidAlive,
-      lastFileActivityAt: '',
-      lastFileActivityLabel: '',
+      lastFileActivityAt: workingLastFileActivityAt,
+      lastFileActivityLabel: workingLastFileActivityLabel,
     };
   }