@imdeadpool/guardex 7.0.41 → 7.0.43

package/src/terminal/tmux.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const tmuxCommand = require('../tmux/command');
+const tmuxSession = require('../tmux/session');
+
+function text(value, fallback = '') {
+  if (typeof value === 'string') return value.trim() || fallback;
+  if (value === null || value === undefined) return fallback;
+  return String(value).trim() || fallback;
+}
+
+function requireText(value, name) {
+  const normalized = text(value);
+  if (!normalized) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return normalized;
+}
+
+function targetId(target) {
+  if (target && typeof target === 'object') {
+    return requireText(target.paneId || target.tmuxPaneId || target.tmuxTarget || target.id || target.target, 'tmux target');
+  }
+  return requireText(target, 'tmux target');
+}
+
+function assertStatus(result, message) {
+  if (result && result.error) throw result.error;
+  if (!result || result.status === 0) return result;
+  const detail = String(result.stderr || result.stdout || '').trim();
+  throw new Error(`${message}${detail ? `: ${detail}` : '.'}`);
+}
+
+function defaultTmuxApi() {
+  return {
+    ensureTmuxAvailable: tmuxSession.ensureTmuxAvailable,
+    sessionExists: tmuxSession.sessionExists,
+    createSession: tmuxSession.createSession,
+    attachSession: tmuxSession.attachSession,
+    newWindowOrPane: tmuxSession.newWindowOrPane,
+    sendKeys: tmuxSession.sendKeys,
+  };
+}
+
+function createBackend(options = {}) {
+  const tmux = options.tmux || defaultTmuxApi();
+  const runTmux = typeof options.runTmux === 'function' ? options.runTmux : tmuxCommand.runTmux;
+
+  return {
+    name: 'tmux',
+    isAvailable() {
+      try {
+        if (typeof tmux.isAvailable === 'function') return Boolean(tmux.isAvailable());
+        tmux.ensureTmuxAvailable();
+        return true;
+      } catch (_error) {
+        return false;
+      }
+    },
+    openCockpitLayout(config = {}) {
+      const sessionName = requireText(config.sessionName, 'tmux sessionName');
+      const repoRoot = requireText(config.repoRoot, 'tmux repoRoot');
+      const command = requireText(config.command, 'tmux cockpit command');
+
+      tmux.ensureTmuxAvailable();
+
+      if (tmux.sessionExists(sessionName)) {
+        assertStatus(tmux.attachSession(sessionName), `tmux could not attach session '${sessionName}'`);
+        return { action: 'attached', sessionName, repoRoot };
+      }
+
+      assertStatus(
+        tmux.createSession(sessionName, repoRoot),
+        `tmux could not create session '${sessionName}'`,
+      );
+      assertStatus(
+        tmux.sendKeys(sessionName, command),
+        'tmux could not start cockpit control pane',
+      );
+
+      if (config.attach) {
+        assertStatus(tmux.attachSession(sessionName), `tmux could not attach session '${sessionName}'`);
+        return { action: 'created-attached', sessionName, repoRoot };
+      }
+      return { action: 'created', sessionName, repoRoot };
+    },
+    launchAgentPane(config = {}) {
+      const session = config.session && typeof config.session === 'object' ? config.session : {};
+      const cwd = requireText(config.worktree || session.worktreePath || session.path, 'tmux agent worktree');
+      const result = tmux.newWindowOrPane({
+        pane: true,
+        split: 'horizontal',
+        target: config.target || session.tmuxTarget || session.tmuxSession || session.sessionName,
+        cwd,
+        name: config.title || session.title,
+      });
+      return assertStatus(result, 'tmux could not launch agent pane');
+    },
+    launchTerminalPane(config = {}) {
+      const result = tmux.newWindowOrPane({
+        pane: true,
+        split: 'horizontal',
+        target: config.target,
+        cwd: requireText(config.cwd, 'tmux terminal cwd'),
+        name: config.title,
+      });
+      return assertStatus(result, 'tmux could not launch terminal pane');
+    },
+    focusPane(target) {
+      return assertStatus(runTmux(['select-pane', '-t', targetId(target)]), 'tmux could not focus pane');
+    },
+    closePane(target) {
+      return assertStatus(runTmux(['kill-pane', '-t', targetId(target)]), 'tmux could not close pane');
+    },
+    sendText(target, value, options = {}) {
+      const args = ['send-keys', '-t', targetId(target), String(value === undefined || value === null ? '' : value)];
+      if (options.submit) args.push('C-m');
+      return assertStatus(runTmux(args), 'tmux could not send text');
+    },
+  };
+}
+
+module.exports = {
+  createBackend,
+  targetId,
+};

package/src/tmux/command.js

@@ -0,0 +1,27 @@
+const runtime = require('../core/runtime');
+
+function assertArgs(args) {
+  if (!Array.isArray(args)) {
+    throw new TypeError('tmux args must be an array');
+  }
+  for (const arg of args) {
+    if (typeof arg !== 'string') {
+      throw new TypeError('tmux args must contain only strings');
+    }
+  }
+}
+
+function runTmux(args, options = {}) {
+  assertArgs(args);
+  return runtime.run(process.env.GUARDEX_TMUX_BIN || 'tmux', args, options);
+}
+
+function isTmuxAvailable() {
+  const result = runTmux(['-V'], { stdio: 'pipe' });
+  return result.status === 0 && !result.error;
+}
+
+module.exports = {
+  isTmuxAvailable,
+  runTmux,
+};

package/src/tmux/session.js

@@ -0,0 +1,89 @@
+const tmux = require('./command');
+
+function requireName(name) {
+  if (typeof name !== 'string' || name.trim() === '') {
+    throw new TypeError('tmux session name must be a non-empty string');
+  }
+  return name;
+}
+
+function addCwd(args, cwd) {
+  if (cwd !== undefined) {
+    if (typeof cwd !== 'string' || cwd.trim() === '') {
+      throw new TypeError('tmux cwd must be a non-empty string');
+    }
+    args.push('-c', cwd);
+  }
+}
+
+function ensureTmuxAvailable() {
+  if (tmux.isTmuxAvailable()) return;
+  throw new Error('tmux is required for gx cockpit. Install tmux and retry.');
+}
+
+function sessionExists(name) {
+  const result = tmux.runTmux(['has-session', '-t', requireName(name)], {
+    stdio: 'pipe',
+  });
+  return result.status === 0;
+}
+
+function createSession(name, cwd) {
+  const args = ['new-session', '-d', '-s', requireName(name)];
+  addCwd(args, cwd);
+  return tmux.runTmux(args);
+}
+
+function attachSession(name) {
+  return tmux.runTmux(['attach-session', '-t', requireName(name)], {
+    stdio: 'inherit',
+  });
+}
+
+function newWindowOrPane(options = {}) {
+  const {
+    target,
+    cwd,
+    name,
+    pane = false,
+    split = 'vertical',
+  } = options;
+  const args = pane ? ['split-window'] : ['new-window'];
+
+  if (pane) {
+    if (split === 'horizontal') {
+      args.push('-h');
+    } else if (split === 'vertical') {
+      args.push('-v');
+    } else {
+      throw new TypeError('tmux split must be horizontal or vertical');
+    }
+  }
+  if (target !== undefined) {
+    args.push('-t', requireName(target));
+  }
+  if (!pane && name !== undefined) {
+    args.push('-n', requireName(name));
+  }
+  addCwd(args, cwd);
+  return tmux.runTmux(args);
+}
+
+function sendKeys(paneId, command) {
+  if (typeof paneId !== 'string' || paneId.trim() === '') {
+    throw new TypeError('tmux pane id must be a non-empty string');
+  }
+  if (typeof command !== 'string') {
+    throw new TypeError('tmux command must be a string');
+  }
+  return tmux.runTmux(['send-keys', '-t', paneId, command, 'C-m']);
+}
+
+module.exports = {
+  ensureTmuxAvailable,
+  sessionExists,
+  createSession,
+  attachSession,
+  newWindowOrPane,
+  sendKeys,
+};

package/templates/AGENTS.multiagent-safety.md

@@ -27,6 +27,7 @@ GUARDEX_ON=1
 - Work from an `agent/*` branch and worktree, never directly on the protected base branch.
 - Claim files before edits.
 - Use Colony for coordination before falling back to OMX state/notepad.
+- Prefer fff MCP tools for file search whenever available; do not route file search through RTK when fff can answer it.
 - Use OpenSpec for durable behavior contracts and change-driven work.
 - Keep outputs compact: less word, same proof.
 - Commit, push, and open/update a PR for completed work unless the user explicitly says to keep it local.
@@ -134,6 +135,25 @@ Default: less word, same proof.
 - Treat local edit/commit, remote publish/PR, CI diagnosis, and cleanup as bounded phases.
 - Do not spend fresh narration or approval turns on obvious safe follow-ons inside an already authorized phase unless the risk changes.
 
+### RTK command compression
+
+When `rtk` is available, prefer it for noisy shell discovery and verification. For file search, fff MCP takes precedence whenever available.
+
+- Files: `rtk ls .`, `rtk read <file>`, `rtk read <file> -l aggressive`, `rtk smart <file>`, `rtk find "<glob>" .`, `rtk grep "<pattern>" .`, `rtk diff <a> <b>`.
+- Git and GitHub: `rtk git status`, `rtk git diff`, `rtk git log -n 10`, `rtk gh pr list`, `rtk gh pr view <id>`.
+- Tests and builds: `rtk test <cmd>`, `rtk err <cmd>`, `rtk jest`, `rtk vitest`, `rtk playwright test`, `rtk pytest`, `rtk cargo test`, `rtk tsc`, `rtk lint`.
+- Runtime and data probes: `rtk docker ps`, `rtk docker logs <container>`, `rtk kubectl pods`, `rtk json <file>`, `rtk log <file>`, `rtk curl <url>`.
+- Savings checks: `rtk gain`, `rtk discover`, and `rtk session`.
+- Use `rtk proxy <command>` only when raw passthrough is required.
+- Do not wrap machine-readable commands with RTK when code parses stdout (`--porcelain`, `--json`, NUL-delimited output, or exact stdout contracts).
+- If `rtk` is missing, use raw commands and summarize only meaningful lines.
+
+### FFF file search
+
+Use the fff MCP tools for all file search operations instead of default tools, including RTK shell wrappers.
+
+If fff MCP tools are unavailable in the current client, fall back to `rtk grep`, `rtk find`, `rtk ls`, or `rg` and keep output compact.
+
 ### Caveman style
 
 Commentary and progress updates use smart-caveman `ultra` by default:
@@ -295,7 +315,13 @@ Task is complete only when:
 
 If anything blocks, append a `BLOCKED:` note and stop. Do not half-finish.
 
-OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR before considering the branch complete.
+OMX completion policy: when a task is done, the agent must run `gx branch finish --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`) instead of standalone `git push` / `gh pr` commands. The finish flow owns commit, push, PR creation/update, merge wait, and sandbox cleanup.
+
+External approval boundary:
+
+- Guardex cannot bypass Codex host approval prompts or external-remote policy decisions.
+- When the host blocks a publish or finish command, request approval for the narrow `gx branch finish ...` command, or for the exact session wrapper that invokes it, and continue after approval.
+- Do not replace the finish flow with repeated standalone `git push` / `gh pr` attempts. That increases approval churn and can strand PR, merge, or cleanup state.
 
 ### Parallel safety
 

package/templates/codex/skills/gitguardex/SKILL.md

@@ -9,3 +9,5 @@ Use when repo safety may be broken.
 
 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/templates/githooks/pre-commit

@@ -207,11 +207,32 @@ fi
 
 if [[ "$branch" == agent/* ]]; then
   if [[ "${GUARDEX_AUTOCLAIM_STAGED_LOCKS:-1}" == "1" ]]; then
+    # Auto-claim non-deletion staged paths. Deletions need an explicit
+    # `--allow-delete` flag below so `locks validate --staged` doesn't
+    # reject the commit on the same trip the user staged the delete.
     while IFS= read -r staged_file; do
       [[ -z "$staged_file" ]] && continue
       [[ "$staged_file" == ".omx/state/agent-file-locks.json" ]] && continue
       run_guardex_cli locks claim --branch "$branch" "$staged_file" >/dev/null 2>&1 || true
-    done < <(git diff --cached --name-only --diff-filter=ACMRDTUXB)
+    done < <(git diff --cached --name-only --diff-filter=ACMRTUXB)
+
+    # Auto-approve deletions for the same branch (gated separately so
+    # operators can disable this single behavior without disabling the
+    # broader auto-claim). Defaults to enabled — matches the auto-claim
+    # default and removes the "first commit fails, then `gx locks
+    # allow-delete`, then commit again" loop.
+    if [[ "${GUARDEX_AUTOCLAIM_STAGED_DELETES:-1}" == "1" ]]; then
+      _staged_deletes=()
+      while IFS= read -r staged_delete; do
+        [[ -z "$staged_delete" ]] && continue
+        [[ "$staged_delete" == ".omx/state/agent-file-locks.json" ]] && continue
+        _staged_deletes+=("$staged_delete")
+      done < <(git diff --cached --name-only --diff-filter=D)
+      if (( ${#_staged_deletes[@]} > 0 )); then
+        run_guardex_cli locks claim --branch "$branch" --allow-delete \
+          "${_staged_deletes[@]}" >/dev/null 2>&1 || true
+      fi
+    fi
   fi
 
   if ! run_guardex_cli locks validate --branch "$branch" --staged; then

package/templates/github/workflows/README.md

@@ -0,0 +1,87 @@
+# `templates/github/workflows/` — budget-friendly CI defaults
+
+Workflow files in this directory are copied into a gitguardex-managed
+project's `.github/workflows/` directory when bootstrapping. They are
+the **default** budget posture for projects that use `gx branch start`
+to drive agent iterations.
+
+Agent flows land a high volume of PRs per month. Without these trims,
+every PR + every post-merge push fans out across CI, CodeQL, Scorecard,
+and Code Review — which dominates the GitHub Actions bill for any
+multi-agent repo. The trims below cut that cost without giving up
+correctness coverage.
+
+## What's trimmed and why
+
+1. **`concurrency: cancel-in-progress: true`** scoped per workflow + ref
+   so rapid pushes to the same agent branch cancel the prior run
+   instead of letting both finish on Actions minutes.
+
+2. **`if: github.event.pull_request.draft == false`** on every job that
+   shouldn't run on a draft PR, paired with
+   `pull_request.types: [..., ready_for_review]` in the trigger list so
+   CI fires the moment the PR is promoted out of draft.
+
+3. **`if: !startsWith(head.ref, 'agent/')`** on the Code Review job
+   (`cr.yml`) — skip AI review on automated agent-lane PRs. AI review
+   on hundreds of agent PRs per month burns both Actions minutes and
+   OpenAI tokens without adding signal; human-authored PRs (any non-
+   `agent/*` head branch) still get reviewed.
+
+4. **No `push: main` trigger** in `ci.yml` — branch protection on
+   `main` forces all changes through a PR, so PR-time CI is sufficient
+   and post-merge CI on `main` was pure duplication. Use
+   `workflow_dispatch` for ad-hoc full runs.
+
+5. **`paths-ignore`** for docs / openspec / template-only changes — skip
+   CI on changes that don't affect runtime behavior.
+
+## Customizing
+
+- Replace `placeholder` steps in `ci.yml` with your build/test/lint
+  commands.
+- Keep the `concurrency:`, `if:`, and `paths-ignore:` patterns. They
+  are the load-bearing part of the budget posture; removing them undoes
+  the win.
+
+## When to skip the draft-skip pattern
+
+If your CI is fast (≤ 2 min) and you want continuous validation as
+agents iterate, drop the `if: pull_request.draft == false` job guard.
+The concurrency cancel alone still prevents minute pile-up.
+
+## When to re-enable AI code review on agent PRs
+
+If your team relies on AI review as a true gating signal (not just
+advisory), remove the `!startsWith(head.ref, 'agent/')` guard in
+`cr.yml`. Expect the OpenAI bill to scale linearly with merge volume.
+
+## Per-PR label opt-in
+
+Both `cr.yml` and `ci-full.yml` honor PR labels so the occasional
+agent PR that actually needs the heavier check can opt in without
+flipping a global toggle:
+
+| Label | Effect |
+| --- | --- |
+| `needs-review` | Run AI code review on this PR even though it's `agent/*`. Useful for security-sensitive changes or public-API redesigns. |
+| `needs-ci-full` | Run the full cross-runtime matrix from `ci-full.yml` on this PR instead of waiting for the weekly schedule. Useful before a release branch lands. |
+
+To enable: open the PR, then `gh pr edit <num> --add-label needs-review`
+(or click the labels picker in the GitHub UI). The label-trigger fires
+the workflow immediately; you don't need to re-push.
+
+Add label definitions to your repo with `gh label create needs-review
+--description "Run AI code review on this PR"` and similar for
+`needs-ci-full`, or define them in `.github/labels.yml` if you use a
+label-sync workflow.
+
+## What about CodeQL / Scorecard?
+
+The gitguardex repo itself runs CodeQL and Scorecard on the **weekly
+schedule + `workflow_dispatch`** only — not on per-PR / per-push
+triggers. Those workflows are long-running (5–10 min for CodeQL) and
+were the largest single line item on the monthly Actions bill before
+this change. If your project needs per-PR CodeQL gating for compliance
+reasons, re-add the `pull_request` trigger and accept the cost; for
+most repos, weekly + on-demand is the right default.

package/templates/github/workflows/ci-full.yml

@@ -0,0 +1,55 @@
+# Optional companion to `ci.yml`. Drop in alongside it when your
+# project supports multiple runtimes / OS combinations and you want
+# coverage across all of them without paying per-PR.
+#
+# Strategy: PR-time `ci.yml` runs the primary runtime only (cheap).
+# This workflow runs the full matrix on the weekly schedule, and
+# on-demand via `workflow_dispatch` before a release. Per-PR opt-in
+# is available by applying the `needs-ci-full` label to a PR.
+#
+# Customize the matrix rows below to match your supported runtimes.
+
+name: CI (full matrix)
+
+on:
+  schedule:
+    - cron: '15 4 * * 1'
+  workflow_dispatch:
+  pull_request:
+    types: [labeled, synchronize]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-full-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (node ${{ matrix.node }})
+    # PR runs only fire when the `needs-ci-full` label is present.
+    # Schedule and workflow_dispatch always run.
+    if: >-
+      github.event_name != 'pull_request' ||
+      contains(github.event.pull_request.labels.*.name, 'needs-ci-full') ||
+      (github.event.action == 'labeled' && github.event.label.name == 'needs-ci-full')
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [18, 22]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: ${{ matrix.node }}
+
+      # Replace below with your build/test/lint steps. Keep them parallel
+      # to `ci.yml` so the weekly matrix matches what runs per-PR.
+      - name: Project verification placeholder
+        run: echo "Replace this step with your build/test/lint commands."

package/templates/github/workflows/ci.yml

@@ -0,0 +1,56 @@
+# Budget-friendly CI default for gitguardex-managed projects.
+#
+# Four trims keep Actions minutes low while agent branches iterate:
+#   1. `concurrency: cancel-in-progress` — rapid pushes to the same ref
+#      kill the prior run instead of letting both finish.
+#   2. Job-level `if: pull_request.draft == false` plus the
+#      `ready_for_review` PR trigger — draft PRs skip CI, and CI fires
+#      automatically the moment the PR is promoted out of draft.
+#   3. `paths-ignore` for docs / openspec / template-only changes —
+#      skip CI on changes that don't affect runtime behavior.
+#   4. No `push: main` trigger — branch-protection-required PR runs
+#      already cover correctness, and post-merge CI on main is pure
+#      duplication. Use `workflow_dispatch` for ad-hoc full runs.
+#
+# Copy this file to `.github/workflows/ci.yml` in your project and
+# replace the placeholder `steps:` block with your build/test/lint
+# commands.
+
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+    types: [opened, reopened, synchronize, ready_for_review]
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+      - 'openspec/**'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/PULL_REQUEST_TEMPLATE.md'
+      - '.changeset/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # Replace below with your build/test/lint steps. Examples:
+      # - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      #   with: { node-version: '20' }
+      # - run: npm ci
+      # - run: npm test
+      - name: Project verification placeholder
+        run: echo "Replace this step with your build/test/lint commands."

package/templates/github/workflows/cr.yml

@@ -2,14 +2,33 @@ name: Code Review
 
 on:
   pull_request:
-    types: [opened, reopened, synchronize]
+    types: [opened, reopened, synchronize, ready_for_review, labeled]
 
 permissions:
   contents: read
   pull-requests: write
 
+# Budget-friendly default for gitguardex-managed projects: cancel
+# superseded runs on the same PR so rapid agent pushes don't fan-out
+# the OpenAI bill.
+concurrency:
+  group: cr-${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
   review:
+    # Skip on draft PRs and on `agent/*` head branches by default.
+    # Agent PRs can opt-in by applying the `needs-review` label —
+    # useful for the occasional agent PR that genuinely needs AI
+    # eyes (security-sensitive change, public-API redesign, etc.).
+    # Human-authored PRs (any non-`agent/*` head branch) always run.
+    if: >-
+      github.event.pull_request.draft == false &&
+      (
+        !startsWith(github.event.pull_request.head.ref, 'agent/') ||
+        contains(github.event.pull_request.labels.*.name, 'needs-review') ||
+        (github.event.action == 'labeled' && github.event.label.name == 'needs-review')
+      )
     runs-on: ubuntu-latest
     env:
       OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}