@dreb/coding-agent 2.49.0 → 2.51.0

package/docs/dashboard.md

@@ -474,3 +474,145 @@ TUI theme system** — dashboard themes intentionally do not map to TUI themes.
   loop; the tree design and RPC are ready).
 - No shell passthrough from the browser.
 - No subagent steering (the drill-in view is read-only).
+
+## Background service / auto-restart
+
+The dashboard runs as a foreground process by default. For it to start on boot
+and restart after crashes, run it as a system service.
+
+### Linux (systemd)
+
+Save a user unit to `~/.config/systemd/user/dreb-dashboard.service`:
+
+```ini
+[Unit]
+Description=dreb web dashboard
+
+[Service]
+ExecStart=%h/.npm-global/bin/dreb-dashboard
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+```
+
+Use the absolute path from `which dreb-dashboard` for `ExecStart` (the example
+matches an npm global prefix under `~/.npm-global`). Then:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now dreb-dashboard
+```
+
+### macOS (launchd)
+
+Create a **LaunchAgent** (not a LaunchDaemon) — the dashboard must run as the
+logged-in user to read `~/.dreb/agent/sessions` and `auth.json`, and to spawn
+`dreb --mode rpc` children under that user. A root LaunchDaemon would have the
+wrong `HOME` and credentials.
+
+Save a plist to `~/Library/LaunchAgents/com.dreb.dashboard.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.dreb.dashboard</string>
+    <!--
+      Invoke node directly on the resolved entry point. The `dreb-dashboard`
+      bin is a #!/usr/bin/env node script; launchd's minimal environment
+      cannot resolve `node` via PATH, so we point ProgramArguments at the
+      absolute node binary and the resolved dist/index.js.
+    -->
+    <key>ProgramArguments</key>
+    <array>
+        <string>/ABSOLUTE/PATH/TO/node</string>
+        <string>/ABSOLUTE/PATH/TO/@dreb/dashboard/dist/index.js</string>
+        <string>--port</string>
+        <string>5343</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <!-- KeepAlive + ThrottleInterval gives crash auto-restart without a tight
+         fail-loop. kill -9 the process and launchd respawns it in seconds. -->
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+    <!--
+      HOME is set automatically for user agents, so ~/.dreb/agent/auth.json
+      (OAuth creds) is found. PATH lets RPC children spawn bash/git/node.
+      If you use API keys via shell environment variables rather than OAuth
+      creds, add the keys here — LaunchAgents do not source shell profiles.
+    -->
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>/Users/YOU/Library/Logs/dreb-dashboard.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/YOU/Library/Logs/dreb-dashboard.err.log</string>
+</dict>
+</plist>
+```
+
+#### Finding the absolute paths
+
+The two `ProgramArguments` paths vary by install method (Homebrew, nvm, bun
+global, npm global prefix). Discover them:
+
+```bash
+command -v node                         # → /opt/homebrew/bin/node
+realpath "$(command -v dreb-dashboard)"   # → /opt/homebrew/lib/node_modules/@dreb/dashboard/dist/index.js
+# If `realpath` is not found, install coreutils: brew install coreutils
+```
+
+Replace `/ABSOLUTE/PATH/TO/node` and `/ABSOLUTE/PATH/TO/@dreb/dashboard/dist/index.js`
+with the actual output. Also replace `/Users/YOU/` in the log paths with your
+home directory.
+
+#### load / unload / status
+
+Use the modern `launchctl bootstrap`/`bootout` API (not the deprecated
+`load`/`unload`):
+
+```bash
+# load / start
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.dreb.dashboard.plist
+# stop / unload
+launchctl bootout gui/$(id -u)/com.dreb.dashboard
+# check state
+launchctl print gui/$(id -u)/com.dreb.dashboard | grep -E 'state|pid'
+```
+
+#### API-key providers
+
+OAuth subscription credentials live in `~/.dreb/agent/auth.json` and are
+found via the auto-set `HOME` — no secrets in the plist. If you use API keys
+via shell environment variables (e.g. `ANTHROPIC_API_KEY`), add them to the
+`EnvironmentVariables` dictionary:
+
+```xml
+<key>EnvironmentVariables</key>
+<dict>
+    <key>PATH</key>
+    <string>…</string>
+    <key>ANTHROPIC_API_KEY</key>
+    <string>sk-ant-…</string>
+</dict>
+```
+
+LaunchAgents do not source `.zshrc`/`.bashrc`/`.profile`, so env vars must be
+set explicitly in the plist.
+
+#### Local vs remote
+
+The plist above runs in local-only mode (binds `127.0.0.1:5343`). For remote
+access from a phone, add `--remote --allow you@example.com` to
+`ProgramArguments` and see the [remote access walkthrough](#local-vs-remote--exactly-two-modes)
+and [TLS setup](#native-tls-remote-https) for the Tailscale + HTTPS path.
+Do not expose the port on your LAN — there is no LAN mode.

package/docs/extensions.md

@@ -613,7 +613,7 @@ In the default parallel tool execution mode, sibling tool calls from the same as
 import { isToolCallEventType } from "@dreb/coding-agent";
 
 dreb.on("tool_call", async (event, ctx) => {
-  // event.toolName - "bash", "read", "write", "edit", "grep", "find", "ls", "web_search", "web_fetch", "subagent", "wait", "search", "ask_user", "skill", "tasks_update", "suggest_next", or custom tool names
+  // event.toolName - "bash", "read", "write", "edit", "grep", "find", "ls", "web_search", "web_fetch", "subagent", "wait", "watch_github_ci", "search", "ask_user", "skill", "tasks_update", "suggest_next", or custom tool names
   // event.toolCallId
   // event.input - tool parameters
 
@@ -1518,7 +1518,7 @@ async execute(toolCallId, params) {
 
 ### Overriding Built-in Tools
 
-Extensions can override built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `web_search`, `web_fetch`, `subagent`, `wait`, `search`, `ask_user`) by registering a tool with the same name. Interactive mode displays a warning when this happens. The factory-only tools (`skill`, `tasks_update`, `suggest_next`) can also be overridden.
+Extensions can override built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `web_search`, `web_fetch`, `subagent`, `wait`, `watch_github_ci`, `search`, `ask_user`) by registering a tool with the same name. Interactive mode displays a warning when this happens. The factory-only tools (`skill`, `tasks_update`, `suggest_next`) can also be overridden.
 
 ```bash
 # Extension's read tool replaces built-in read
@@ -1549,6 +1549,8 @@ Built-in tool implementations:
 - [ls.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/ls.ts) - `LsToolDetails`
 - [web.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/web.ts) - `web_search` and `web_fetch`
 - [subagent.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/subagent.ts)
+- [wait.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/wait.ts)
+- [watch-github-ci.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/watch-github-ci.ts) - `watch_github_ci`
 - [skill.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/skill.ts) - factory-only
 - [tasks.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/tasks.ts) - factory-only
 

package/docs/mach6.md

@@ -30,7 +30,7 @@ Assess an existing GitHub issue or create a new one.
 /skill:mach6-issue add dark mode   # Create issue from description
 ```
 
-**Assess mode:** Launches parallel subagents to explore the codebase, then posts a structured assessment (summary, gaps, ambiguities, scope, risks) as an issue comment.
+**Assess mode:** Launches parallel Explore agents to retrieve bounded code/documentation evidence, then has the primary agent synthesize and post the assessment (summary, gaps, ambiguities, scope, risks) as an issue comment.
 
 **Create mode:** Drafts a structured issue with title, summary, acceptance criteria, and technical notes.
 
@@ -44,7 +44,7 @@ Explore the codebase, create an implementation plan, open a draft PR, and post t
 
 - Reads the issue and any existing assessment
 - Checks project conventions (AGENTS.md, CONTRIBUTING.md, etc.)
-- Launches parallel subagents to explore similar features, architecture, and integration points
+- Launches parallel Explore agents to locate related implementations, enumerate explicit flows/call sites, and quote bounded evidence; the primary agent owns architecture and planning
 - Creates a feature branch (`feature/issue-42-<slug>`) with an empty commit
 - Opens a draft PR linking to the issue
 - Posts the plan as a PR comment with `<!-- mach6-plan -->` marker
@@ -112,7 +112,7 @@ Pre-merge checks, version bump, docs update, merge, tag, and release.
 /skill:mach6-publish 53
 ```
 
-- Verifies CI passing, no merge conflicts, all findings addressed
+- Verifies CI passing with the blocking `watch_github_ci` tool (never `wait` or a polling loop), no merge conflicts, and all findings addressed
 - Runs pre-merge checklist (version bump, tests)
 - Applies version bump on the feature branch
 - Proactively reviews and updates ALL documentation affected by the PR's changes

package/docs/rpc.md

@@ -1112,7 +1112,7 @@ Response:
       },
       {
         "name": "Explore",
-        "description": "Codebase and web exploration — find files, search code, search the web, answer questions. Read-only."
+        "description": "Concrete evidence retrieval — locate files, symbols, documentation, call sites, and exact snippets. No implementation work."
       }
     ]
   }

package/docs/sdk.md

@@ -387,10 +387,10 @@ const { session } = await createAgentSession({ resourceLoader: loader });
 
 ```typescript
 import {
-  codingTools,   // read, bash, edit, write (subset — default is all 11)
+  codingTools,   // read, bash, edit, write (subset — default is all 13 standard tools)
   readOnlyTools, // read, grep, find, ls
   readTool, bashTool, editTool, writeTool,
-  grepTool, findTool, lsTool,
+  grepTool, findTool, lsTool, watchGithubCiTool,
 } from "@dreb/coding-agent";
 
 // Use built-in tool set
@@ -953,13 +953,13 @@ SettingsManager
 codingTools
 readOnlyTools
 readTool, bashTool, editTool, writeTool
-grepTool, findTool, lsTool
+grepTool, findTool, lsTool, watchGithubCiTool
 
 // Tool factories (for custom cwd)
 createCodingTools
 createReadOnlyTools
 createReadTool, createBashTool, createEditTool, createWriteTool
-createGrepTool, createFindTool, createLsTool
+createGrepTool, createFindTool, createLsTool, createWatchGithubCiTool
 
 // Types
 type CreateAgentSessionOptions

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dreb/coding-agent",
-	"version": "2.49.0",
+	"version": "2.51.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"drebConfig": {

package/skills/mach6-implement/SKILL.md

@@ -18,7 +18,7 @@ This skill has two modes:
 2. **No `#N` in comment bodies** — Use "finding 3", "item 3" etc. instead.
 3. **Safe git** — Never use `git add -A` or `git add .`. Stage files by name. Never stage secrets.
 4. **Task tracking** — Use the `tasks_update` tool to show progress.
-5. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
+5. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
 
 ## Parent ownership and the formal-review checkpoint
 
@@ -133,13 +133,14 @@ tasks_update([
 
 #### If `ci` was specified:
 
+Use `watch_github_ci` with `pr: "<pr-number>"` so the tool blocks until the pull request's checks pass or fail. Do not use `wait`, sleep, or repeated polling commands for CI.
+
+If checks fail, use the returned check output to identify the failed run, then inspect it:
+
 ```bash
-gh pr checks <pr-number>
 gh run view <run-id> --log-failed
 ```
 
-**Note:** `gh pr checks` returns exit code 8 while checks are still pending — this is expected, not a failure. Wait and re-run if needed.
-
 Read the failed CI logs and identify issues. Extract test failures, stack traces, error messages. If all checks pass, report this and stop.
 
 #### If finding numbers were specified:

package/skills/mach6-issue/SKILL.md

@@ -16,7 +16,7 @@ argument-hint: "[issue-number | description]"
 4. **Safe git** — Never use `git add -A` or `git add .`. Stage files by name. Never stage secrets (.env, credentials, tokens, keys).
 5. **Task tracking** — Use the `tasks_update` tool to show progress through multi-step commands.
 6. **Project conventions** — Check for CLAUDE.md, AGENTS.md, .dreb/CONTEXT.md, and CONTRIBUTING.md before planning or implementing.
-7. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
+7. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
 
 ## Determine Mode
 
@@ -52,12 +52,12 @@ Update task: read → completed, explore → in_progress.
 
 ### Step 3: Explore the codebase
 
-Launch 2-3 Explore subagents in parallel targeting different aspects. Agent definitions specify their own model with a provider fallback list — defaults work across providers and are fine for most cases. Override only with good reason (e.g. a particularly complex issue warrants a stronger tier).
-- **Relevant code**: Find existing code related to the issue, trace implementation patterns
-- **Architecture**: Map relevant architecture layers, abstractions, data flow
-- **Prior work**: Check for related branches, PRs, or commits
+Launch 2-3 Explore subagents in parallel for concrete evidence retrieval. Agent definitions specify their own model with a provider fallback list — defaults work across providers and are fine for most cases. Override only with good reason (e.g. a large repository requires inspecting many files).
+- **Relevant code evidence**: Locate named related behavior and quote the exact implementation and test snippets
+- **Flow inventory**: Enumerate files, symbols, imports, calls, and registrations in an explicitly named existing flow without diagnosing it
+- **Prior-work evidence**: Locate related branches, PRs, commits, and documentation and report their exact references
 
-Each agent should return 5-10 key files. After agents complete, read all identified files.
+Do not ask Explore to determine the root cause, interpret ambiguous requirements, recommend an implementation, decide architecture, or assess the issue. Each agent should return 5-10 key files with bounded evidence. After agents complete, read all identified files and have the primary agent synthesize the current state, gaps, scope, and risks.
 
 Update task: explore → completed, assess → in_progress.
 
@@ -76,7 +76,7 @@ Present to the user:
 Post as an issue comment:
 
 ```bash
-GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"
+GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"
 cat > "$GH_BODY" << 'MACH6_EOF'
 <!-- mach6-assessment -->
 ## Issue Assessment
@@ -109,7 +109,7 @@ ls .github/ISSUE_TEMPLATE/ 2>/dev/null
 ```
 If templates exist, read them and select the most appropriate one.
 
-Explore the codebase if needed to understand the relevant area.
+If codebase context is needed, use Explore subagents only for bounded evidence such as locating named behavior, files, tests, call sites, or exact snippets. The primary agent must interpret that evidence and own the issue's requirements, proposed behavior, scope, and technical conclusions.
 
 ### Step 2: Draft the issue
 
@@ -128,7 +128,7 @@ Present the draft to the user for approval.
 ### Step 3: Create the issue
 
 ```bash
-GH_BODY="$(mktemp /tmp/gh-body.XXXXXX.md)"
+GH_BODY="$(mktemp /tmp/gh-body.$$.XXXXXXXX)"
 cat > "$GH_BODY" << 'MACH6_EOF'
 <body>
 MACH6_EOF

package/skills/mach6-plan/SKILL.md

@@ -18,7 +18,7 @@ This command is strictly for **planning**. Do NOT implement any code changes —
 4. **Safe git** — Never use `git add -A` or `git add .`. Stage files by name. Never stage secrets.
 5. **Task tracking** — Use the `tasks_update` tool to show progress through multi-step commands.
 6. **Project conventions** — Check for CLAUDE.md, AGENTS.md, .dreb/CONTEXT.md, and CONTRIBUTING.md before planning.
-7. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
+7. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
 
 ## Step 1: Set up task tracking
 
@@ -53,12 +53,12 @@ Extract planning-relevant guidance: project layers, testing expectations, coding
 
 ## Step 4: Explore the codebase
 
-Launch 2-3 Explore subagents in parallel. Agent definitions specify their own model with a provider fallback list — defaults work across providers and are fine for most cases. Override only with good reason (e.g. a particularly large or complex codebase warrants a stronger tier).
-- **Similar features**: Find existing code that solves related problems, trace implementation patterns
-- **Architecture**: Map relevant architecture layers, abstractions, data flow
-- **Integration points**: Identify where new code connects to existing systems
+Launch 2-3 Explore subagents in parallel for concrete evidence retrieval. Agent definitions specify their own model with a provider fallback list — defaults work across providers and are fine for most cases. Override only with good reason (e.g. a particularly large codebase requires inspecting many files).
+- **Existing feature evidence**: Locate named related features and quote the exact implementation and test snippets that establish their patterns
+- **Layer inventory**: Enumerate the files, symbols, imports, and calls in an explicitly named existing data flow without deciding the architecture
+- **Integration evidence**: Enumerate concrete call sites, registrations, configuration, and documentation for the relevant symbols
 
-Include project conventions in each agent's context. Each agent returns 5-10 key files. Read all identified files.
+Do not ask Explore to diagnose the problem, interpret ambiguous requirements, recommend an implementation, design the architecture, or produce the plan. Include project conventions in each agent's context. Each agent returns 5-10 key files with bounded evidence. Read all identified files, then have the primary agent synthesize the architecture, risks, and implementation plan.
 
 Update task: explore → completed, plan → in_progress.
 
@@ -98,7 +98,7 @@ git commit --allow-empty -m "chore: open PR for issue <N>"
 git push -u origin feature/issue-<N>-<slug>
 
 # Open draft PR
-GH_BODY="$(mktemp /tmp/gh-body.XXXXXX.md)"
+GH_BODY="$(mktemp /tmp/gh-body.$$.XXXXXXXX)"
 cat > "$GH_BODY" << 'MACH6_EOF'
 Closes #<N>
 
@@ -114,7 +114,7 @@ Update task: branch → completed, post → in_progress.
 ## Step 7: Post plan to PR
 
 ```bash
-GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"
+GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"
 cat > "$GH_BODY" << 'MACH6_EOF'
 <!-- mach6-plan -->
 ## Implementation Plan

package/skills/mach6-publish/SKILL.md

@@ -14,7 +14,7 @@ argument-hint: "<pr-number>"
 2. **No `#N` in comment bodies** — Use "finding 3", "item 3" etc. instead.
 3. **Safe git** — Never use `git add -A` or `git add .`. Stage files by name. Never stage secrets.
 4. **Task tracking** — Use the `tasks_update` tool to show progress.
-5. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
+5. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
 
 ## Step 1: Set up task tracking
 
@@ -34,10 +34,9 @@ tasks_update([
 gh pr checkout <pr-number>
 git pull
 gh pr view <pr-number> --json mergeable,mergeStateStatus,statusCheckRollup,reviewDecision,comments,body
-gh pr checks <pr-number>
 ```
 
-**Note:** `gh pr checks` returns exit code 8 while checks are still pending — this is expected, not a failure. Wait and re-run if needed.
+Use `watch_github_ci` with `pr: "<pr-number>"` to block until CI passes or fails. Do not use `wait`, sleep, or repeated polling commands for CI.
 
 Read ALL PR comments to understand the full history — plans, reviews, assessments, progress updates, and discussion.
 
@@ -90,7 +89,7 @@ Update task: checks → completed, version → in_progress.
    git push
    ```
 
-5. Wait for CI to pass on the version bump commit before proceeding to merge.
+5. Use `watch_github_ci` with `pr: "<pr-number>"` and proceed only after it reports that CI passed on the version bump commit.
 
 If the project doesn't use versioning, skip this step.
 
@@ -127,7 +126,7 @@ Proactively review and update ALL documentation affected by the PR's changes. Th
    git push
    ```
 
-5. Wait for CI to pass on the docs commit.
+5. Use `watch_github_ci` with `pr: "<pr-number>"` and proceed only after it reports that CI passed on the docs commit.
 
 If no documentation changes are needed (rare), skip this step.
 
@@ -181,7 +180,7 @@ git push --tags
 
 3. Present draft to user for approval, then create:
    ```bash
-   GH_NOTES="$(mktemp /tmp/gh-release-notes.XXXXXX.md)"
+   GH_NOTES="$(mktemp /tmp/gh-release-notes.$$.XXXXXXXX)"
    cat > "$GH_NOTES" << 'MACH6_EOF'
    <release-notes>
    MACH6_EOF

package/skills/mach6-push/SKILL.md

@@ -15,7 +15,7 @@ argument-hint: "[commit message]"
 3. **No `#N` in comment bodies** — Use "finding 3", "item 3", "stage 2" etc. instead.
 4. **Safe git** — Never use `git add -A` or `git add .`. Stage files by name. Never stage secrets (.env, credentials, tokens, keys).
 5. **Task tracking** — Use the `tasks_update` tool to show progress.
-6. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
+6. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
 7. **Stop after durable progress** — The commit, push, and GitHub progress comment are the accountability and recovery boundary. Do not invoke `mach6-review` or continue into a formal review cycle. Only the user may start formal review; offer it with `suggest_next` and stop.
 
 ## Step 1: Set up task tracking
@@ -82,7 +82,7 @@ If session context points to an issue but a PR also exists on the current branch
 
 Post a progress comment:
 ```bash
-GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"
+GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"
 cat > "$GH_BODY" << 'MACH6_EOF'
 <!-- mach6-progress -->
 ## Progress Update

package/skills/mach6-review/SKILL.md

@@ -14,7 +14,7 @@ argument-hint: "<pr-number> [code|errors|tests|completeness|simplify]"
 2. **HTML markers** — Use `<!-- mach6-review -->` and `<!-- mach6-assessment -->` as the first line of comment bodies.
 3. **No `#N` in comment bodies** — Use "finding 3", "item 3", "stage 2" etc. instead.
 4. **Task tracking** — Use the `tasks_update` tool to show progress.
-5. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
+5. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
 6. **User-controlled checkpoint** — This formal multi-agent review runs only from an explicit user request, either through its slash command or a direct instruction to an agent to invoke it. An agent may invoke it in response to that request; otherwise agents must only offer it with `suggest_next`, never invoke it autonomously or start a review-fix-review loop.
 7. **Review durable work only** — Do not launch formal review agents against uncommitted or unpushed work. The commit, push, and GitHub progress comment are the accountability and recovery boundary.
 
@@ -126,7 +126,7 @@ Update task: review → completed, post-review → in_progress.
 Compile all findings from all agents into a single structured comment:
 
 ```bash
-GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"
+GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"
 cat > "$GH_BODY" << 'MACH6_EOF'
 <!-- mach6-review -->
 ## Code Review
@@ -195,7 +195,7 @@ Update task: assess → completed, post-assess → in_progress.
 ## Step 7: Post assessment
 
 ```bash
-GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"
+GH_BODY="$(mktemp /tmp/gh-comment.$$.XXXXXXXX)"
 cat > "$GH_BODY" << 'MACH6_EOF'
 <!-- mach6-assessment -->
 ## Review Assessment
@@ -229,7 +229,7 @@ Present to the user:
 
 If any findings were classified as **deferred**, ask the user if they want to create issues for them:
 ```bash
-GH_BODY="$(mktemp /tmp/gh-body.XXXXXX.md)"
+GH_BODY="$(mktemp /tmp/gh-body.$$.XXXXXXXX)"
 cat > "$GH_BODY" << 'MACH6_EOF'
 <body referencing PR and finding>
 MACH6_EOF