@imdeadpool/guardex 7.0.41 → 7.0.43

package/README.md

@@ -24,10 +24,11 @@
   <a href="#01--install-in-one-line">Install</a> ·
   <a href="#03--what-it-does">What it does</a> ·
   <a href="#04--daily-workflow">Workflow</a> ·
-  <a href="#05--what-gx-shows-first">gx status</a> ·
-  <a href="#07--commands">Commands</a> ·
-  <a href="#08--v6--v7-migration">Migration</a> ·
-  <a href="#10--companion-tools">Companions</a>
+  <a href="#05--dmux-style-multi-agent-cockpit">Cockpit</a> ·
+  <a href="#06--what-gx-shows-first">gx status</a> ·
+  <a href="#08--commands">Commands</a> ·
+  <a href="#09--v6--v7-migration">Migration</a> ·
+  <a href="#11--companion-tools">Companions</a>
 </p>
 
 ---
@@ -56,6 +57,12 @@ gx setup   # hooks, state, OMX / OpenSpec / caveman wiring — one shot
 > feels rough — especially around **cleanup**, **finish**, **merge**, or
 > **recovery** flows — sorry. We're patching as we find things.
 
+> [!CAUTION]
+> **Recommended default: macOS or Linux with Codex CLI.** OMX is primarily
+> designed and actively tuned for that path. Native Windows and Codex App are
+> not the default experience, may break or behave inconsistently, and currently
+> receive less support.
+
 ---
 
 ## The problem
@@ -135,7 +142,30 @@ gx branch finish --branch "$(git rev-parse --abbrev-ref HEAD)" \
 
 ---
 
-## `05` &nbsp;What `gx` shows first
+## `05` &nbsp;dmux-style multi-agent cockpit
+
+GitGuardex now has a dmux-style cockpit for starting, inspecting, and
+finishing isolated agent lanes from one terminal workspace. It is not a
+dmux clone: GitGuardex keeps safety as the core and adds orchestration
+on top of isolated worktrees, file locks, protected base branches, and
+PR-only finish.
+
+```bash
+gx cockpit
+gx agents start "fix auth tests" --agent codex --base main --claim test/auth.test.js
+gx agents start "fix auth tests" --panel --codex-accounts 3 --base main
+gx agents start "update setup docs" --agent claude --base main --claim README.md
+gx agents status
+gx agents files --branch agent/codex/fix-auth-tests-2026-04-29-21-30
+gx agents diff --branch agent/claude/update-setup-docs-2026-04-29-21-31
+gx agents finish --branch agent/codex/fix-auth-tests-2026-04-29-21-30
+```
+
+Long-form guide: [docs/agents-cockpit.md](./docs/agents-cockpit.md).
+
+---
+
+## `06` &nbsp;What `gx` shows first
 
 Before you branch, repair, or start agents, run plain `gx`. It gives you
 a one-screen status for the CLI, global helpers, repo safety service,
@@ -170,7 +200,7 @@ the compact layout everywhere.
 
 ---
 
-## `06` &nbsp;How `AGENTS.md` is handled
+## `07` &nbsp;How `AGENTS.md` is handled
 
 > [!IMPORTANT]
 > **GitGuardex never overwrites your guidance.** Only content between
@@ -182,12 +212,13 @@ the compact layout everywhere.
 | --- | --- |
 | `AGENTS.md` **with** markers | Refreshes **only** the managed block. |
 | `AGENTS.md` **without** markers | Appends the managed block to the end. |
-| No `AGENTS.md` | Creates it with the managed block. |
+| No `AGENTS.md` | Creates it with the managed block, then links `CLAUDE.md` to it. |
+| No root `CLAUDE.md` | Creates a `CLAUDE.md` symlink to `AGENTS.md`. |
 | A root `CLAUDE.md` | Leaves it alone. |
 
 ---
 
-## `07` &nbsp;Commands
+## `08` &nbsp;Commands
 
 ### Core
 
@@ -209,6 +240,18 @@ the compact layout everywhere.
 | `gx sync` | Sync current agent branch against base. |
 | `gx release` | Update the GitHub release from README notes. |
 
+### Multi-agent cockpit
+
+| command | does |
+| --- | --- |
+| `gx cockpit` | Create or attach to a repo tmux cockpit session with a status pane. |
+| `gx agents start "<task>" --agent codex` | Start an isolated Codex lane for a task. |
+| `gx agents start "<task>" --agent claude` | Start an isolated Claude Code lane for a task. |
+| `gx agents status` | Show repo agent service status. |
+| `gx agents files --branch <agent/...>` | List files changed by one agent lane. |
+| `gx agents diff --branch <agent/...>` | Show the diff for one agent lane. |
+| `gx agents finish --branch <agent/...>` | Finish one agent session through the existing PR flow. |
+
 ```bash
 gx release  # create/update the current GitHub release from README notes
 ```
@@ -227,7 +270,7 @@ gx protect reset   # back to: dev · main · master
 
 ---
 
-## `08` &nbsp;v6 → v7 migration
+## `09` &nbsp;v6 → v7 migration
 
 Five commands were consolidated into flags. Old names still work and
 print a deprecation notice; they'll be removed in v8.
@@ -245,7 +288,7 @@ print a deprecation notice; they'll be removed in v8.
 
 ---
 
-## `09` &nbsp;Known rough edges
+## `10` &nbsp;Known rough edges
 
 Being honest about where this still has issues:
 
@@ -265,6 +308,18 @@ Being honest about where this still has issues:
 <details open>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.42
+- Bumped `@imdeadpool/guardex` from `7.0.41` to `7.0.42` so the current
+  `main` payload can publish under a fresh npm version after `7.0.41` reached
+  the registry.
+- Improves the agent-session and cockpit workflow: `gx agents start/status`
+  now share canonical session storage, agent lanes can be previewed, claimed,
+  finished by session, and launched through safer supported-agent metadata,
+  and cockpit can render live session state through tmux-backed panes.
+- Hardens setup and status hygiene by ignoring local `.codex/` state during
+  setup/doctor, avoiding generic OpenSpec dirty-worktree reuse, and pruning
+  stale agent sessions from user-facing status surfaces.
+
 ### 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`
@@ -316,13 +371,13 @@ Being honest about where this still has issues:
 
 ---
 
-## `10` &nbsp;Companion tools
+## `11` &nbsp;Companion tools
 
 All optional — but if you're running many agents, you probably want them.
 `gx status` auto-detects each one and reports it in the `Global services`
 block.
 
-Install repo skills with `npx skills add recodee/gitguardex`; `npx skills add recodee/` opens the recodee namespace. `gx setup` does not auto-run `npx skills add ...`. If the picker does not show a separate `guardex` skill, that is expected.
+Install repo skills with `npx skills add recodee/gitguardex`; the npm package also ships the root `skills/` catalog so the npx installer can read the GitGuardex skill from the published tarball. `npx skills add recodee/` opens the recodee namespace. `gx setup` does not auto-run `npx skills add ...`. If the picker does not show a separate `guardex` skill, that is expected.
 
 | Tool | What it does | Stars |
 | --- | --- | --- |
@@ -333,7 +388,7 @@ Install repo skills with `npx skills add recodee/gitguardex`; `npx skills add re
 | [**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) |
-| [**GitHub CLI (`gh`)**](https://github.com/cli/cli) — see [cli.github.com](https://cli.github.com/) | Required for PR / merge automation. `gx branch finish --via-pr --wait-for-merge` depends on it. | [![stars](https://img.shields.io/github/stars/cli/cli?style=social)](https://github.com/cli/cli) |
+| [**GitHub CLI (`gh`)**](https://github.com/cli/cli) — see [cli.github.com](https://cli.github.com/) | Required for PR / merge automation. `gx branch finish --via-pr --wait-for-merge` depends on it. If `ghx` is on `PATH`, Guardex uses that GitHub CLI cache proxy automatically; set `GUARDEX_GH_BIN=gh` to force direct `gh`. | [![stars](https://img.shields.io/github/stars/cli/cli?style=social)](https://github.com/cli/cli) |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.41",
+  "version": "7.0.43",
   "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,
@@ -39,6 +39,7 @@
   "files": [
     "bin",
     "src",
+    "skills",
     "templates",
     "README.md",
     "LICENSE",

package/skills/gitguardex/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: gitguardex
+description: "Repo guardrail check and repair."
+---
+
+Use when repo safety may be broken.
+
+`gx status` -> `gx doctor` -> `gx status --strict`
+
+Bootstrap: `gx setup`
+Ops: `gx branch start "<task>" "<agent>"`, `gx locks claim --branch "<agent-branch>" <file...>`, `gx branch finish --branch "<agent-branch>" --base <base> --via-pr --wait-for-merge --cleanup`, `gx finish --all`, `gx cleanup`
+
+When inspecting or verifying, prefer `rtk` compact wrappers if available (`rtk git status`, `rtk grep`, `rtk test <cmd>`). Do not wrap commands whose stdout is parsed by scripts.

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

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

package/src/agents/cleanup-sessions.js

@@ -0,0 +1,126 @@
+const fs = require('node:fs');
+
+const {
+  listAgentSessions,
+  removeAgentSession,
+} = require('./sessions');
+const { branchExists: defaultBranchExists } = require('../git');
+const { TOOL_NAME } = require('../context');
+
+const DEFAULT_STALE_AGE_MINUTES = 24 * 60;
+const TERMINAL_STATUSES = new Set(['finished', 'pr-opened', 'failed']);
+
+function parseTimestamp(value) {
+  if (!value) return null;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : null;
+}
+
+function sessionAgeMinutes(session, nowMs) {
+  const timestamp = parseTimestamp(session.updatedAt) ?? parseTimestamp(session.createdAt);
+  if (timestamp === null) return null;
+  return Math.max(0, Math.floor((nowMs - timestamp) / 60000));
+}
+
+function evaluateSession(session, repoRoot, options) {
+  const reasons = [];
+  const worktreePath = session.worktreePath || '';
+  const branch = session.branch || '';
+
+  if (worktreePath && !options.existsSync(worktreePath)) {
+    reasons.push('missing-worktree');
+  }
+
+  if (branch && !options.branchExists(repoRoot, branch)) {
+    reasons.push('missing-branch');
+  }
+
+  const status = session.status || '';
+  const ageMinutes = sessionAgeMinutes(session, options.nowMs);
+  if (
+    TERMINAL_STATUSES.has(status)
+    && ageMinutes !== null
+    && ageMinutes >= options.staleAgeMinutes
+  ) {
+    reasons.push('terminal-status-old');
+  }
+
+  return {
+    ...session,
+    ageMinutes,
+    reasons,
+    stale: reasons.length > 0,
+  };
+}
+
+function cleanupAgentSessions(repoRoot, rawOptions = {}) {
+  const options = {
+    dryRun: Boolean(rawOptions.dryRun),
+    staleAgeMinutes: rawOptions.staleAgeMinutes ?? DEFAULT_STALE_AGE_MINUTES,
+    nowMs: rawOptions.nowMs ?? Date.now(),
+    existsSync: rawOptions.existsSync || fs.existsSync,
+    branchExists: rawOptions.branchExists || defaultBranchExists,
+  };
+
+  const sessions = listAgentSessions(repoRoot);
+  const candidates = sessions
+    .map((session) => evaluateSession(session, repoRoot, options))
+    .filter((session) => session.stale);
+
+  const removed = [];
+  if (!options.dryRun) {
+    for (const session of candidates) {
+      if (removeAgentSession(repoRoot, session.id)) {
+        removed.push(session.id);
+      }
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    repoRoot,
+    dryRun: options.dryRun,
+    staleAgeMinutes: options.staleAgeMinutes,
+    inspected: sessions.length,
+    candidates,
+    removed,
+  };
+}
+
+function formatSessionLine(session, verb) {
+  const reasonText = session.reasons.join(',');
+  return `- ${verb} ${session.id} status=${session.status || '-'} branch=${session.branch || '-'} ` +
+    `worktree=${session.worktreePath || '-'} reasons=${reasonText}`;
+}
+
+function renderCleanupSessionsResult(result, options = {}) {
+  if (options.json) return `${JSON.stringify(result, null, 2)}\n`;
+
+  const action = result.dryRun ? 'would remove' : 'removed';
+  const lines = [
+    `[${TOOL_NAME}] Agent session cleanup: ${action} ${result.dryRun ? result.candidates.length : result.removed.length} ` +
+      `of ${result.inspected} (${result.repoRoot})`,
+  ];
+
+  if (result.candidates.length === 0) {
+    lines.push('- no stale session metadata found');
+  } else {
+    for (const session of result.candidates) {
+      lines.push(formatSessionLine(session, action));
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function runCleanupSessionsCommand(repoRoot, options = {}) {
+  return renderCleanupSessionsResult(cleanupAgentSessions(repoRoot, options), options);
+}
+
+module.exports = {
+  DEFAULT_STALE_AGE_MINUTES,
+  TERMINAL_STATUSES,
+  cleanupAgentSessions,
+  renderCleanupSessionsResult,
+  runCleanupSessionsCommand,
+};

package/src/agents/detect.js

@@ -0,0 +1,160 @@
+const registry = require('./registry');
+const { run } = require('../core/runtime');
+
+function registryEntries() {
+  if (typeof registry.getAgentDefinitions === 'function') {
+    const definitions = registry.getAgentDefinitions();
+    if (Array.isArray(definitions)) {
+      return definitions;
+    }
+  }
+
+  if (Array.isArray(registry.AGENT_IDS) && typeof registry.getAgentDefinition === 'function') {
+    return registry.AGENT_IDS
+      .map((agentId) => registry.getAgentDefinition(agentId))
+      .filter((entry) => entry && typeof entry === 'object');
+  }
+
+  const source =
+    registry.agents ||
+    registry.AGENTS ||
+    registry.registry ||
+    registry.entries ||
+    registry.default ||
+    registry;
+
+  if (Array.isArray(source)) {
+    return source;
+  }
+
+  if (source && typeof source === 'object') {
+    return Object.entries(source)
+      .filter(([, entry]) => entry && typeof entry === 'object')
+      .map(([id, entry]) => ({ id, ...entry }));
+  }
+
+  return [];
+}
+
+function findAgent(agentId) {
+  if (typeof registry.getAgentDefinition === 'function') {
+    const entry = registry.getAgentDefinition(agentId);
+    if (entry) return entry;
+  }
+
+  if (typeof registry.resolveAgent === 'function') {
+    try {
+      const entry = registry.resolveAgent(agentId);
+      if (entry) return entry;
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  if (typeof registry.getAgent === 'function') {
+    const entry = registry.getAgent(agentId);
+    if (entry) return entry;
+  }
+
+  return registryEntries().find((entry) => entry.id === agentId);
+}
+
+function registryAgentIds() {
+  if (Array.isArray(registry.AGENT_IDS)) {
+    return [...registry.AGENT_IDS];
+  }
+
+  if (typeof registry.getAgentDefinitions === 'function') {
+    const definitions = registry.getAgentDefinitions();
+    if (Array.isArray(definitions)) {
+      return definitions.map((entry) => entry && entry.id).filter(Boolean);
+    }
+  }
+
+  return registryEntries().map((entry) => entry.id).filter(Boolean);
+}
+
+function normalizeDetectCommand(detectCommand) {
+  if (Array.isArray(detectCommand)) {
+    const [cmd, ...args] = detectCommand;
+    return { cmd, args, command: detectCommand.join(' ') };
+  }
+
+  if (typeof detectCommand === 'string') {
+    const [cmd, ...args] = detectCommand.trim().split(/\s+/).filter(Boolean);
+    return { cmd, args, command: detectCommand.trim() };
+  }
+
+  if (detectCommand && typeof detectCommand === 'object') {
+    const cmd = detectCommand.cmd || detectCommand.command || detectCommand.bin;
+    const args = Array.isArray(detectCommand.args) ? detectCommand.args : [];
+    return {
+      cmd,
+      args,
+      command: [cmd, ...args].filter(Boolean).join(' '),
+    };
+  }
+
+  return { cmd: null, args: [], command: null };
+}
+
+function resultError(result) {
+  if (result.error) {
+    return result.error.message || String(result.error);
+  }
+
+  const output = `${result.stderr || ''}${result.stdout || ''}`.trim();
+  if (output) return output;
+
+  if (typeof result.status === 'number') {
+    return `detect command exited with status ${result.status}`;
+  }
+
+  return 'detect command failed';
+}
+
+function detectionResult(entry, available, command, error = null) {
+  return {
+    id: entry.id,
+    label: entry.label || entry.id,
+    available,
+    command,
+    error,
+  };
+}
+
+function detectAgent(agentId) {
+  const entry = findAgent(agentId);
+  if (!entry) {
+    const known = registryAgentIds();
+    const suffix = known.length > 0 ? ` (known agents: ${known.join(', ')})` : '';
+    return detectionResult({ id: agentId, label: agentId }, false, null, `unknown agent: ${agentId}${suffix}`);
+  }
+
+  const { cmd, args, command } = normalizeDetectCommand(entry.detectCommand);
+  if (!cmd) {
+    return detectionResult(entry, false, command, 'missing detectCommand');
+  }
+
+  const result = run(cmd, args, { stdio: 'pipe' });
+  if (!result.error && result.status === 0) {
+    return detectionResult(entry, true, command, null);
+  }
+
+  return detectionResult(entry, false, command, resultError(result));
+}
+
+function detectAgents(agentIds) {
+  const ids = Array.isArray(agentIds) ? agentIds : registryAgentIds();
+  return ids.map((agentId) => detectAgent(agentId));
+}
+
+function detectAvailableAgents() {
+  return detectAgents().filter((agent) => agent.available);
+}
+
+module.exports = {
+  detectAgent,
+  detectAgents,
+  detectAvailableAgents,
+};