@imdeadpool/guardex 7.0.21 → 7.0.23

package/README.md

@@ -1,12 +1,8 @@
 <p align="center">
-  <img alt="gitguardex logo" src="./logo.png" width="260">
+  <img alt="gitguardex logo" src="./logo.png" width="390">
 </p>
 
-<h1 align="center">gitguardex</h1>
-
-<p align="center">
-  guardian t-rex for multi-agent repos
-</p>
+<h1 align="center"> guardian t-rex for multi-agent repos</h1>
 
 <p align="center">
   isolated worktrees, file locks, and PR-only merges for codex, claude, and human teammates
@@ -14,6 +10,9 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@imdeadpool/guardex"><img alt="npm version" src="https://img.shields.io/npm/v/%40imdeadpool%2Fguardex?label=npm&style=flat-square&color=cb3837&logo=npm&logoColor=white"></a>
+  <a href="https://www.npmjs.com/package/@imdeadpool/guardex"><img alt="npm downloads per month" src="https://img.shields.io/npm/dm/%40imdeadpool%2Fguardex?label=downloads%2Fmonth&style=flat-square&color=0b76c5"></a>
+  <a href="https://github.com/recodeee/gitguardex/actions/workflows/ci.yml"><img alt="CI status" src="https://img.shields.io/github/actions/workflow/status/recodeee/gitguardex/ci.yml?branch=main&label=CI&style=flat-square"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/recodeee/gitguardex"><img alt="OpenSSF Scorecard" src="https://img.shields.io/ossf-scorecard/github.com/recodeee/gitguardex?label=OpenSSF%20Scorecard&style=flat-square"></a>
   <a href="https://github.com/recodeee/gitguardex/stargazers"><img alt="stars" src="https://img.shields.io/github/stars/recodeee/gitguardex?label=stars&style=flat-square&color=d4ac0d"></a>
   <a href="https://github.com/recodeee/gitguardex/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/recodeee/gitguardex?label=last%20commit&style=flat-square&color=7aa2f7"></a>
   <a href="./LICENSE"><img alt="license" src="https://img.shields.io/npm/l/%40imdeadpool%2Fguardex?label=license&style=flat-square&color=97ca00"></a>
@@ -28,14 +27,30 @@
   <a href="#commands">Commands</a>
 </p>
 
+
+<h3 align="center">Install in one line</h3>
+
+```bash
+npm i -g @imdeadpool/guardex
+```
+
+<p align="center">
+  <sub>
+    Then <code>cd</code> into your repo and run <code>gx setup</code> — hook shims, repo state,
+    and OMX&nbsp;/&nbsp;OpenSpec&nbsp;/&nbsp;caveman wiring all scaffold in one go.
+  </sub>
+</p>
+
 <p align="center">
   <strong>guard many agent. keep one repo clean.</strong>
 </p>
 
+[about_description.txt](./about_description.txt)
+
+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.
+
 <p align="center">
-  GitGuardex is a safety layer for parallel agent work in git repos. Every task gets an isolated
-  worktree, claimed files, and a PR-only finish path instead of one shared checkout where agents
-  stomp each other.
+  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.
 </p>
 
 ---
@@ -66,25 +81,6 @@ GitGuardex exists to stop that loop. Every agent gets its own worktree, claims t
   <img alt="Install GitGuardex" src="https://raw.githubusercontent.com/recodeee/gitguardex/main/docs/images/install-hero.svg" width="680">
 </p>
 
-<h3 align="center">Install in one line</h3>
-
-```bash
-npm i -g @imdeadpool/guardex
-```
-
-<p align="center">
-  <sub>
-    Then <code>cd</code> into your repo and run <code>gx setup</code> — hook shims, repo state,
-    and OMX&nbsp;/&nbsp;OpenSpec&nbsp;/&nbsp;caveman wiring all scaffold in one go.
-  </sub>
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@imdeadpool/guardex"><img alt="npm" src="https://img.shields.io/npm/v/%40imdeadpool%2Fguardex?label=latest&style=flat-square&color=cb3837&logo=npm&logoColor=white"></a>
-  <a href="https://www.npmjs.com/package/@imdeadpool/guardex"><img alt="downloads" src="https://img.shields.io/npm/dm/%40imdeadpool%2Fguardex?label=downloads&style=flat-square&color=0b76c5"></a>
-  <a href="https://github.com/recodeee/gitguardex/stargazers"><img alt="stars" src="https://img.shields.io/github/stars/recodeee/gitguardex?style=flat-square&color=d4ac0d"></a>
-</p>
-
 ### Dashboard
 
 ![Multi-agent dashboard example](https://raw.githubusercontent.com/recodeee/gitguardex/main/docs/images/dashboard-multi-agent.png)
@@ -270,7 +266,7 @@ To install the real companion into local VS Code from a GitGuardex-wired repo:
 node scripts/install-vscode-active-agents-extension.js
 ```
 
-It adds an `Active Agents` view to the Source Control container, groups each live repo into `ACTIVE AGENTS` and `CHANGES` sections, splits `ACTIVE AGENTS` into `BLOCKED`, `WORKING NOW`, `IDLE`, `STALLED`, and `DEAD` when those states are present, reads `.omx/state/active-sessions/*.json`, derives session state from git conflict markers, dirty worktree status, PID liveness, and recent file mtimes, and surfaces working/dead counts in the repo/header affordances. Reload the VS Code window after install.
+It adds an `Active Agents` view to the Source Control container, groups each live repo into `ACTIVE AGENTS` and `CHANGES` sections, splits `ACTIVE AGENTS` into `BLOCKED`, `WORKING NOW`, `IDLE`, `STALLED`, and `DEAD` when those states are present, mirrors the selected session or active-agent count in the VS Code status bar, reads `.omx/state/active-sessions/*.json`, derives session state from git conflict markers, dirty worktree status, PID liveness, and recent file mtimes, and surfaces working/dead counts in the repo/header affordances. Reload the VS Code window after install.
 
 ---
 
@@ -344,6 +340,7 @@ gx sync
 ```sh
 gx agents start           # review monitor + stale cleanup
 gx agents stop
+gx agents stop --pid 12345
 gx agents status
 
 # tuning
@@ -372,6 +369,9 @@ That GitHub release then triggers `.github/workflows/release.yml`, which perform
 ```sh
 gx prompt                 # full checklist (paste into Codex/Claude)
 gx prompt --exec          # commands only
+gx prompt --part task-loop
+gx prompt --exec --part finish --part cleanup
+gx prompt --list-parts
 gx prompt --snippet       # AGENTS.md managed-block template
 ```
 
@@ -672,6 +672,16 @@ npm pack --dry-run
 <details>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.23
+- Bumped `@imdeadpool/guardex` from `7.0.22` to `7.0.23` so GitHub release and npm can advance together after `7.0.22` reached npm without a matching published GitHub release.
+- Active Agents stays easier to scan and more truthful: the package repo remains the canonical source, inspect/install paths stay loadable across VS Code churn, and session rows group under worktrees with clearer merged-cleanup truth.
+- Guardex prompt and finish guidance now pushes faster phase-based execution, keeps helper behavior single-sourced, and avoids fragmented probe loops when cleanup or branch-deletion races appear.
+
+### v7.0.22
+- Bumped `@imdeadpool/guardex` from `7.0.21` to `7.0.22` so npm can publish the next release from the current merged mainline.
+- The shipped `main` payload already includes lower-token prompt slices, SCM-selected lane visibility, truthful merged-cleanup evidence, the Active Agents brand/icon refresh, and the remaining CLI extraction cleanups without changing Guardex behavior.
+- Keep the release scoped to version and release metadata only; the package payload stays the same as the verified `main` branch contents.
+
 ### v7.0.21
 - Bumped `@imdeadpool/guardex` from `7.0.20` to `7.0.21` so npm can publish the next release from the current merged mainline.
 - Keep the release scoped to version and release metadata only; the package payload stays the same as the verified `main` branch contents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.21",
+  "version": "7.0.23",
   "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,
@@ -69,5 +69,9 @@
   },
   "devDependencies": {
     "fast-check": "^3.23.2"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1",
+    "semver": "^7.7.4"
   }
 }

package/src/cli/args.js

@@ -271,6 +271,7 @@ function parseAgentsArgs(rawArgs) {
     reviewIntervalSeconds: 30,
     cleanupIntervalSeconds: 60,
     idleMinutes: DEFAULT_SHADOW_CLEANUP_IDLE_MINUTES,
+    pid: null,
   };
 
   for (let index = 0; index < rest.length; index += 1) {
@@ -314,12 +315,28 @@ function parseAgentsArgs(rawArgs) {
       index += 1;
       continue;
     }
+    if (arg === '--pid') {
+      const next = rest[index + 1];
+      if (!next) {
+        throw new Error('--pid requires a positive integer value');
+      }
+      const parsedValue = Number.parseInt(next, 10);
+      if (!Number.isInteger(parsedValue) || parsedValue <= 0) {
+        throw new Error('--pid must be a positive integer');
+      }
+      options.pid = parsedValue;
+      index += 1;
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}`);
   }
 
   if (!['start', 'stop', 'status'].includes(options.subcommand)) {
     throw new Error(`Unknown agents subcommand: ${options.subcommand}`);
   }
+  if (options.pid !== null && options.subcommand !== 'stop') {
+    throw new Error('--pid is only supported with `gx agents stop`');
+  }
 
   return options;
 }
@@ -332,6 +349,15 @@ function parseReportArgs(rawArgs) {
     scorecardJson: '',
     outputDir: '',
     date: '',
+    taskSize: '',
+    tokens: '',
+    execCount: '',
+    writeStdinCount: '',
+    completionBeforeTail: '',
+    expectedBound: '',
+    fragmentation: '',
+    finishPath: '',
+    postProof: '',
     dryRun: false,
     json: false,
   };
@@ -373,6 +399,69 @@ function parseReportArgs(rawArgs) {
       index += 1;
       continue;
     }
+    if (arg === '--task-size') {
+      const next = rawArgs[index + 1];
+      if (!next) throw new Error('--task-size requires a value');
+      options.taskSize = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--tokens') {
+      const next = rawArgs[index + 1];
+      if (!next) throw new Error('--tokens requires a value');
+      options.tokens = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--exec-count') {
+      const next = rawArgs[index + 1];
+      if (!next) throw new Error('--exec-count requires a value');
+      options.execCount = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--write-stdin-count') {
+      const next = rawArgs[index + 1];
+      if (!next) throw new Error('--write-stdin-count requires a value');
+      options.writeStdinCount = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--completion-before-tail') {
+      const next = rawArgs[index + 1];
+      if (!next) throw new Error('--completion-before-tail requires yes or no');
+      options.completionBeforeTail = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--expected-bound') {
+      const next = rawArgs[index + 1];
+      if (!next) throw new Error('--expected-bound requires a value');
+      options.expectedBound = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--fragmentation') {
+      const next = rawArgs[index + 1];
+      if (!next) throw new Error('--fragmentation requires a value');
+      options.fragmentation = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--finish-path') {
+      const next = rawArgs[index + 1];
+      if (!next) throw new Error('--finish-path requires a value');
+      options.finishPath = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--post-proof') {
+      const next = rawArgs[index + 1];
+      if (!next) throw new Error('--post-proof requires a value');
+      options.postProof = next;
+      index += 1;
+      continue;
+    }
     if (arg === '--dry-run') {
       options.dryRun = true;
       continue;