Add OpenClaw workflow dashboard

.gitignore

@@ -4,3 +4,4 @@ src/generated.ts
 dist/
 .wrangler/
 .pnpm-store/
+.artifacts/

README.md

@@ -10,6 +10,7 @@ Crabfleet gives OpenClaw maintainers a fleet dashboard where every Codex crabbox
 
 - **Fleet-first workflow.** Create repo-ready Crabboxes from the app, SSH, or the Go CLI and see org Codex instances grouped by person.
 - **Board-based workflow.** Create cards from prompts, GitHub issues, or PRs. Track them through Todo, Running, Human Review, and Done lanes.
+- **Claw Queue workflow.** Pick ClawSweeper-screened OpenClaw issues, choose Codex thinking mode, hand work to local Codex, track parallel plates, and copy maintainer-ready handoffs.
 - **Issue/PR lookup.** Type `#123` in search to preview matching GitHub issues or PRs across enabled OpenClaw repos and create a card from the match.
 - **Codex run control.** Start durable run attempts, track heartbeats, watch the Ghostty WASM session grid, and take over only when the selected runtime advertises that capability.
 - **Interactive Crabboxes.** Start a standalone Codex CLI workspace for manual cloud work and attach it in the same fullscreen Ghostty grid or WebVNC.
@@ -61,6 +62,27 @@ Add users/teams to the allowlist and enable repos:
 - **From issue:** Search GitHub issues → create card
 - **From PR:** Search GitHub PRs → create card for review/fix
 
+### 3b. Use Claw Queue
+
+Open `/app/claw-queue` when you want OpenClaw issue triage instead of a generic board card.
+
+- Configure role, target repo, GitHub login, usage limit, worker count, default Thinking mode, and minimum issue age.
+- Paste a specific GitHub issue URL or number when the issue you want is not shown in the queue.
+- Choose per-issue Thinking and Proof mode before copying a prompt, tracking manual work, or starting Codex.
+- Use Blade actions to inspect issue or PR GitHub pages in a side panel while keeping the queue, loop, or active-work context visible.
+- Connect the local Codex bridge with `pnpm openclaw:runner -- --workspace <path-to-openclaw> --worktree-dir <path-to-openclaw-worktrees> --port 4545 --max-active 2 --reasoning-effort high --token <secret-token>`.
+- Install Tokenjuice with `npm install -g tokenjuice` and `tokenjuice install codex` when you want started workers to compact noisy terminal output.
+- Start or safe Track posts a marker-backed "working on this" issue claim through your local `gh` auth before the Codex run is launched or recorded; coverage-investigation tracks do not pretend the issue is claimed.
+- Use Command Center first; it picks the next eligible issue, active plate, or blocked state.
+- Use `/app/claw-loop` for the full-width Master Loop swimlanes across ready issues, validation, coding, PR readiness, handoff, and completed work.
+- Reject unsuitable queue candidates from Claw Queue or Loop to hide them locally with a reason, then restore them from the Local rejects panel if needed.
+- Use Active Work to track parallel Codex/tmux/app sessions, copy each Codex worktree path, watch local run logs, and keep each PR visible until it is ready, parked, or archived.
+- When the local bridge is connected, Claw Queue can use Gitcrawl's local OpenClaw store for broad queue rows, possible PR coverage, authored open PR rows, and cached check hints while live GitHub remains the final source for claims, PR-limit gates, PR updates, and CI truth.
+- Start Codex runs include a bounded local skill packet from `%USERPROFILE%\.codex\skills` and the common OpenClaw maintainer skills checkout by default, so workers know where the relevant OpenClaw, Gitcrawl, Tokenjuice, Crabbox, ClawSweeper, PR review, security, CI, and Codex review skills live on the machine.
+- For loopback-only local preview without GitHub OAuth or a bootstrap token, set `CRABFLEET_DEV_IDENTITY=1` so the login screen shows the Dev Identity Apply panel.
+
+See [Claw Queue docs](docs/claw-queue.md).
+
 ### 4. Watch Runs
 
 - Running cards show D1 event logs and heartbeat state

docs/_layouts/default.html

@@ -220,6 +220,7 @@ <h2>Start</h2>
           <a href="{{ '/quickstart/' | relative_url }}">Quickstart</a>
           <a href="{{ '/architecture/' | relative_url }}">Architecture</a>
           <h2>Features</h2>
+          <a href="{{ '/claw-queue/' | relative_url }}">Claw Queue</a>
           <a href="{{ '/cards/' | relative_url }}">Cards</a>
           <a href="{{ '/runs/' | relative_url }}">Runs</a>
           <a href="{{ '/admin/' | relative_url }}">Admin</a>

docs/api.md

@@ -126,6 +126,141 @@ Maintainer+. Searches enabled repos for issue/PR number matches.
 
 With `GITHUB_TOKEN`, lookup runs across all enabled repos. Without it, lookup falls back to the preferred repo.
 
+## Claw Queue
+
+Claw Queue uses same-origin app endpoints for OpenClaw workflow state and a separate local loopback bridge for Codex handoff.
+
+### GET /api/openclaw/workflow
+
+Viewer+. Returns the configured OpenClaw workflow pack for the current user.
+
+Optional query parameters:
+
+- `repo`: normalized `owner/repo` target repo.
+- `login`: GitHub login used for authored open PR monitoring.
+
+Response includes:
+
+- `preferences`: role, repo, GitHub login, worker count, Codex reasoning effort, usage limits, and issue age gate.
+- `queues`: ClawSweeper-screened queue definitions, search queries, candidates, totals, per-queue errors, and candidate `possiblePrCoverage` warnings when recent open PRs directly reference an issue.
+- `pullRequests`: authored open PR summaries with CI and ClawSweeper signals.
+- `governor`: whether new work can start, plus open PR and usage-limit reasons.
+- `process`: links to OpenClaw contributing files and maintainer guardrails.
+
+### GET /api/openclaw/issue
+
+Viewer+. Loads one specific OpenClaw issue by URL, `#number`, or number. Use this when the issue is not currently visible in the queue.
+
+Optional query parameters:
+
+- `input`: required issue URL, `#number`, or number.
+- `repo`: normalized `owner/repo` fallback for plain numbers.
+
+Response includes:
+
+- `repo`: repo used for the lookup.
+- `issueNumber`: loaded issue number.
+- `candidate`: the same candidate shape used by queue rows, including labels, ClawSweeper readiness, age gate, generated prompt, and `possiblePrCoverage`.
+- `coverageError`: warning text when the possible PR coverage scan was partial or failed.
+
+### PUT /api/openclaw/preferences
+
+Viewer+. Saves the current user's Claw Queue preferences.
+
+```json
+{
+  "roleMode": "trial_maintainer",
+  "targetRepo": "openclaw/openclaw",
+  "githubLogin": "octocat",
+  "activeOpenPrLimit": 10,
+  "dailyUsageDropLimit": 5,
+  "maxParallelWorkers": 2,
+  "codexReasoningEffort": "high",
+  "minimumIssueAgeHours": 6,
+  "weeklyRemainingBaseline": 97,
+  "weeklyRemainingCurrent": 92
+}
+```
+
+### POST /api/openclaw/handoff
+
+Viewer+. Builds the short Discord-ready maintainer handoff text.
+
+```json
+{
+  "prUrl": "https://github.com/openclaw/openclaw/pull/123",
+  "issueUrl": "https://github.com/openclaw/openclaw/issues/99",
+  "title": "#123 Fix queue guard",
+  "summary": "Queue guard now respects linked PR labels.",
+  "proof": "pnpm test and Codex review passed.",
+  "ci": "CI green",
+  "clawsweeper": "ready for maintainer look"
+}
+```
+
+### Local Codex Bridge
+
+The browser talks directly to the local bridge configured in Claw Queue, normally `http://127.0.0.1:4545`.
+
+Bridge endpoints:
+
+```text
+GET /health
+GET /runs
+GET /runs/:id
+GET /runs/:id/log
+PATCH /runs/:id
+POST /claim
+POST /start
+POST /track
+POST /gitcrawl/coverage
+POST /gitcrawl/workflow
+```
+
+Every bridge request requires:
+
+```text
+Authorization: Bearer <runner-token>
+```
+
+Start the bridge from the repo checkout:
+
+```bash
+pnpm openclaw:runner -- --workspace <path-to-openclaw> --worktree-dir <path-to-openclaw-worktrees> --port 4545 --max-active 2 --reasoning-effort high --token <secret-token>
+```
+
+Add `--dry-run` to record prompts and Active Work rows without launching Codex.
+
+`--reasoning-effort` can also be provided with `OPENCLAW_CODEX_REASONING_EFFORT`. The default is `high`.
+
+By default the bridge scans `%USERPROFILE%\.codex\skills` plus the common OpenClaw maintainer skills checkout at `%LOCALAPPDATA%\OpenClawMaintainer\repos\maintainers\.agents\skills`, then injects a bounded list of relevant local `SKILL.md` paths into every `/start` prompt. Use `--skills-dir <path>` or `OPENCLAW_CODEX_SKILLS_DIR` to override the primary Codex skill location. Use `--maintainer-skills-dir <path>`, `OPENCLAW_MAINTAINER_SKILLS_DIR`, or `OPENCLAW_MAINTAINERS_DIR` to point at a different maintainer checkout. Use `--no-skill-context` to disable the skill packet.
+
+The bridge also reports and injects the resolved Tokenjuice command for output compaction. Use `--tokenjuice-bin <path>` or `TOKENJUICE_BIN` if `tokenjuice` is not on `PATH`. Workers should use `tokenjuice doctor hooks` to verify hook health and `tokenjuice wrap --raw -- <command>` when exact raw output is required.
+
+`GET /health` reports `defaultReasoningEffort`, `baseWorkspace`, `worktreeDir`, `worktreeBase`, and `tokenjuiceCommand`. `GET /runs` and `GET /runs/:id` include each run's `codexReasoningEffort`, `proofMode`, `baseWorkspace`, `worktreePath`, and `worktreeBranch` when known.
+
+For `/start`, `--workspace` is treated as the clean base checkout. The bridge creates a unique git worktree and branch for each Codex process, then launches Codex inside that worktree. This keeps parallel starts isolated from each other. `/track` records external/manual work and does not create a worktree.
+
+`POST /claim` accepts `{ "repo": "owner/repo", "issueNumber": 123, "issueUrl": "https://github.com/owner/repo/issues/123", "title": "Issue title" }`. It uses the local `gh` CLI to post a marker-backed issue comment, or returns the existing marker-backed claim if the same bridge/user already claimed that issue. Claw Queue calls this before `/start` and `/track`, then stores `claimCommentStatus` and `claimCommentUrl` on the run.
+
+`POST /gitcrawl/coverage` accepts `{ "repo": "owner/repo", "issueNumbers": [123] }` and returns local Gitcrawl snapshot PR coverage for displayed issues. It checks open PR titles and indexed excerpts, so Codex prompts still tell workers to re-check GitHub before coding.
+
+`POST /gitcrawl/workflow` accepts `{ "repo": "owner/repo", "githubLogin": "user", "roleMode": "trial_maintainer", "minimumIssueAgeHours": 6 }` and returns one local Gitcrawl snapshot for Claw Queue broad reads:
+
+- queue definitions and candidates for the selected role,
+- possible open PR coverage for those candidates,
+- authored open PR rows and any cached check rows for the configured login,
+- snapshot metadata including `lastSyncAt`.
+
+The browser prefers this snapshot for broad queue/coverage reads when the local bridge is connected, then keeps live GitHub data for final issue state, claim comments, PR-limit gates, PR updates, and CI truth. Set `OPENCLAW_GITCRAWL_DB_PATH` on the bridge to point directly at a Gitcrawl SQLite store; otherwise the bridge runs `gitcrawl doctor --json` and caches the result briefly.
+
+`POST /start` and `POST /track` accept:
+
+- `codexReasoningEffort`: `low`, `medium`, `high`, or `xhigh`.
+- `proofMode`: `auto`, `local`, `crabbox`, `testbox`, or `mantis`.
+
+The bridge records both values on the run. `/start` launches Codex with `model_reasoning_effort="<value>"`; `/track` only records the manually started work. Omitted or invalid reasoning values fall back to `high` or the bridge's `--reasoning-effort` default. Omitted or invalid proof modes fall back to `auto`.
+
 ## Cards
 
 ### POST /api/cards

docs/claw-queue-brief.md

@@ -0,0 +1,94 @@
+---
+title: Claw Queue Brief
+layout: default
+permalink: /claw-queue/brief/
+description: "A human-readable one-page summary of the Claw Queue workflow."
+---
+
+# Claw Queue: One-Page Summary
+
+Claw Queue is an OpenClaw-focused workflow layer inside Crabfleet. Its goal is to help contributors and trial maintainers turn good GitHub issues into good PRs without losing track of the process, the proof, or the work already in progress.
+
+It does not replace GitHub, ClawSweeper, maintainers, or the existing contribution rules. It sits on top of them and makes the path from "this issue looks queueable" to "this PR is ready for maintainer review" clearer and harder to get wrong.
+
+## The Problem
+
+OpenClaw already has useful issue queues, labels, ClawSweeper comments, CI checks, Mantis proof when available, and contribution guidance. The problem is that a contributor still has to join those pieces together manually.
+
+That becomes especially messy when someone is juggling more than one Codex session or local terminal. It is easy to pick an issue that already has a PR, miss a higher-priority queue, forget to wait for ClawSweeper, open a PR without enough proof, lose track of CI, or ask maintainers to review something that is not actually ready.
+
+## What Claw Queue Does
+
+Claw Queue turns that scattered process into one operating surface.
+
+It can:
+
+- show ClawSweeper-screened queueable issues in priority order,
+- prefer issues with no linked/open PR and warn when recent open PRs appear to reference the same issue,
+- load a specific issue by URL or number when the user already knows what they want to inspect,
+- support contributor, trial-maintainer, and maintainer modes,
+- apply personal limits such as open PR count, worker count, usage budget, and minimum issue age,
+- choose a default Codex thinking mode, choose a proof route, and override both per issue before launch,
+- pass Tokenjuice output-compaction guidance to started workers and copy/paste prompts,
+- use Crabbox or Blacksmith Testbox for remote/cross-version validation when local proof is not enough,
+- generate a complete Codex-ready prompt for a selected issue,
+- open issue and PR context in a side GitHub blade while keeping the queue visible,
+- post or reuse a marker-backed issue claim comment before starting or tracking safe work,
+- connect to a local Codex bridge to start or track work,
+- track active work across Codex, tmux, local shells, or manual copy/paste,
+- show a short inline activity tail for bridge-managed Codex runs,
+- show a Master Loop swimlane view across ready issues, validation, coding, PR readiness, maintainer handoff, handoff sent, and completed work,
+- monitor authored PRs for CI, ClawSweeper readiness, proof labels, and Mantis visibility,
+- produce a short Discord-ready maintainer handoff when a PR is ready.
+
+The important shift is that the page is not only an issue picker. It tries to carry the work through the whole contribution loop.
+
+For data discovery, Claw Queue follows the same pattern used elsewhere in the OpenClaw ecosystem: archive/cache first for broad issue and PR discovery, live GitHub only for final verification and mutations. The Worker still asks live GitHub for final state, but when the local Codex bridge is connected the page also reads a Gitcrawl workflow snapshot for broad queue rows, possible PR coverage, and authored open PR rows. The local snapshot is not final authority for bypassing live open-PR limits. The next production-grade step is a central Gitcrawl-backed snapshot source so hosted Crabfleet can do the same without relying on each user's local store.
+
+## How The Workflow Feels
+
+The user starts in Command Center. If new work is allowed, it shows the next safest issue to pick. If work is already active, it helps resume or close out that plate instead. If limits, GitHub errors, usage budget, or worker capacity block new work, it says so directly.
+
+Master Loop is the controller view at `/app/claw-loop`. It reads the same queue, active-work, PR, CI, proof, and ClawSweeper state and classifies every visible item into full-width swimlanes. In the current safe phase it observes, explains, and recommends the next action. Later phases can auto-move rows, generate handoffs, and start Codex workers within user limits.
+
+Queue candidates can be rejected locally from either Claw Queue rows or Loop swimlane candidate cards. This is a personal hide list with a reason and restore action, not a GitHub mutation. It is meant for cases where a trial maintainer manually confirms an item is not suitable, already has a linked PR, needs a decision, or otherwise should not keep appearing as available work.
+
+When a user starts or tracks an issue, Claw Queue uses the local bridge and the user's `gh` auth to post or find the "working on this" claim comment when the issue is safe to claim. If possible PR coverage is still unknown, Track records the investigation without pretending the issue is claimed. Each active row records the selected thinking mode, proof mode, and claim state, can be resumed, linked to a PR, marked ready, parked, or archived. For Start Codex runs, the local bridge creates a separate git worktree and branch per issue, then exposes that path in Active Work. Worker Runway shows how many local plates are open based on the user's worker count, so running two or three parallel Codex jobs becomes isolated and visible rather than remembered in someone's head.
+
+For users who cannot or do not want to start Codex directly from the page, Claw Queue still provides a copy/paste prompt. That prompt tells Codex to use Tokenjuice for noisy terminal output when available, re-check the issue and any possible PR coverage, read the current OpenClaw guidance, follow ClawSweeper, keep the fix focused, run tests, use Codex review, monitor CI, and stop only when the PR is genuinely ready for maintainer look.
+
+The prompt also carries maintainer-handbook guardrails. Release-sensitive work needs release-branch awareness, plugin install/update/SDK/package work needs maintainer discussion and broader contract validation, security-adjacent work should be escalated without public vulnerability metadata, and issues owned by another OpenClaw repo should be routed instead of patched in the wrong place. For a trial maintainer, the target outcome is evidence and a handoff, not merge authority.
+
+## What Counts As Done
+
+In this workflow, "done" does not mean "a PR exists."
+
+Done means:
+
+- the issue is linked,
+- the fix is focused,
+- proof or tests are included,
+- Codex review has been run,
+- CI is green or failures are clearly explained,
+- ClawSweeper/status labels indicate readiness,
+- the maintainer handoff is short enough to post directly in Discord.
+
+If proof is not good enough and Mantis is unavailable or broken, the correct outcome is to park the work with a clear blocker note rather than push a weak PR.
+
+## Why It Matters
+
+For contributors, Claw Queue should make OpenClaw work less intimidating and less ambiguous.
+
+For trial maintainers, it provides a responsible way to help with high-priority issues without needing merge permissions.
+
+For maintainers, it should reduce duplicate, incomplete, or low-proof PRs and make review requests easier to act on.
+
+For Codex users, it gives the agent a process-aware work order instead of a bare issue link.
+
+The bigger aim is to make OpenClaw contribution work feel less chaotic: pick the right issue, start it with the right instructions, track the active plates, prove the fix, watch the PR, and hand it to maintainers only when it is ready.
+
+## Current Shape
+
+This is currently built as an OpenClaw-specific Crabfleet feature. It can be tested safely against a fork with dummy issues and PRs, and the local Codex bridge supports dry-run mode so the workflow can be demonstrated without launching real work.
+
+The next useful proof is to test it hard against forked OpenClaw issues and PRs, then decide whether it should remain a Crabfleet feature, be proposed upstream, or become a more general contributor workflow surface.