Squad Control Integration

Orchestrate AI agent tasks from Squad Control's kanban board.

Critical Rules

• - Blocked-task dedup: Before posting a blocked status update, check the thread for your most recent message. If your last message is already a blocked update AND no new messages have been posted since, do NOT post another blocked comment — exit and wait for next dispatch instead.
• Incremental thread fetching: Use ?limit=N when reading thread history to avoid loading the full thread. If you know the last message ID from a previous session, save it in agentState so the next dispatch only fetches new messages.
• Use agentState for continuity: On pickup, check task.agentState for prior session context (files modified, steps completed, decisions made). Save state mid-task via POST /api/tasks/save-state.

Quick Reference

• - Setup: INLINECODE4
• Full API: INLINECODE5
• PR template: INLINECODE6
• Review checklist: INLINECODE7
• Poll result schema: INLINECODE8
• Migration notes: INLINECODE9
• Wake listener: INLINECODE10

Required env vars: SC_API_URL, SC_API_KEY

---

Task Polling Flow

When a cron fires to check for tasks:

1. 1. Run ~/.openclaw/skills/squad-control/scripts/poll-tasks.sh (requires SC_API_URL and SC_API_KEY env vars)

- Script is multi-workspace safe: it does not export top-level REPO_URL / GITHUB_TOKEN; resolve repo/token per task from task.workspace (or fallback top-level workspace for legacy payloads). - Script includes overlap protection via a lock/lease guard (stale lock auto-expires). - Script uses retry/backoff/timeouts for API calls.

1. 2. If output is HEARTBEAT_OK → no work, stop
2. If output contains POLL_RESULT: → parse the JSON envelope after it:

- pending → follow Pickup & Dispatch below for each task - review.tasks → follow Review Dispatch below for each task - stuck.tasks → follow Stuck Task Recovery below for each task

⚠️ Isolated session fallback: If sessions_spawn is not available (e.g. this is an isolated cron session), do NOT hallucinate completion. Instead, hand off to the main session:

> openclaw agent --agent main --channel telegram -m "SQUAD_CONTROL_DISPATCH: pending tasks need worker sessions spawned. Use the squad-control skill. POLL_RESULT:
> <paste the full POLL_RESULT JSON here>"
> 

Then reply HEARTBEAT_OK and exit. The main session has sessions_spawn and will handle dispatch.

Alternatively, call the APIs directly:

• - Pending: INLINECODE27
• Review: INLINECODE28

Parse workspace config from the response (see Multi-Workspace Response Handling below).

Wake Listener Flow

When a cron fires to run the wake listener:

1. 1. Run INLINECODE29
2. The script first calls POST /api/wake/session and opens an outbound relay connection when the wake relay is configured
3. When a wake signal arrives, the script immediately runs poll-tasks.sh and captures the resulting POLL_RESULT envelope
4. If pending.tasks contains assigned work, the listener launches an ACP worker session directly via the local authenticated POST /api/sessions/spawn endpoint instead of routing through a second dispatcher LLM turn
5. If there is no direct pending work but review.tasks or stuck.tasks remain, the listener spawns a local openclaw agent turn for the residual dispatcher work
6. The wake-listener cron session can then exit cleanly; future wakes will be handled by the next listener run
7. If the relay is unavailable, it falls back to GET /api/wake/poll and uses the same handoff rule after the first wake
8. If the local /api/sessions/spawn endpoint returns 404/405/410/501 on an older OpenClaw build, the listener caches that capability miss for a while and falls back to the chat dispatcher path without retrying the same 404 on every wake

Use this when you want low-latency async dispatch without exposing a public OpenClaw gateway URL.
The listener stays outbound-only; the existing 15-minute poll cron remains the final fallback recovery path.

Multi-Workspace Response Handling

INLINECODE40 can return tasks from multiple workspaces when using an account-level API key. Each task includes an embedded workspace object with all config needed to work on it.

Response shape — workspace-scoped key (legacy / single-workspace):

{
  "workspace": { "_id": "wsId", "name": "MyApp", "repoUrl": "...", "githubToken": "..." },
  "tasks": [{ "_id": "taskId", "title": "...", "agent": { ... } }]
}

→ workspace is at the top level; tasks do not have their own workspace object.

Response shape — account-scoped key (multi-workspace):

{
  "tasks": [
    {
      "_id": "taskId",
      "title": "...",
      "workspace": {
        "_id": "wsId",
        "name": "MyApp",
        "repoUrl": "https://github.com/org/repo",
        "githubToken": "ghp_...",
        "agentConcurrency": 3
      },
      "agent": { ... }
    }
  ]
}

→ Each task carries its own workspace object. Tasks from different workspaces may appear in the same response.

Agent fields — always nested under task.agent (never flat on task root):

{
  "agent": {
    "_id": "agentId",
    "name": "Cody",
    "role": "Developer",
    "model": "anthropic/claude-sonnet-4-6",
    "soulMd": "..."
  }
}

⚠️ Do NOT use task.agentName — that field does not exist. Always use task.agent.name, task.agent.model, task.agent.soulMd, task.agent._id.

Handling both shapes (backward compatible):

CODEBLOCK4

Concurrency per workspace: When tasks from multiple workspaces are returned, apply agentConcurrency per workspace independently. Do not count agents running for workspace A against workspace B's limit.

CODEBLOCK5

Stuck Task Recovery

Run two checks every cron cycle:

Check 1 — Tasks stuck in "working" with a PR deliverable:

curl -sL "${SC_API_URL}/api/tasks/list?status=working" -H "x-api-key: ${SC_API_KEY}"

For each working task where deliverables contains a PR entry, startedAt exists, and startedAt is more than 30 minutes ago (and no recent activity signal) → auto-rescue by moving to review.

Before rescue, apply idempotency guards:

1. 1. Skip if task already has an autoRescuedAt marker in metadata (if available)
2. Skip if thread already contains an auto-rescue message for this task
3. After successful rescue, write marker autoRescuedAt=<now> (or equivalent) to prevent duplicate rescues in later cron cycles

CODEBLOCK7
Only post thread message if set-review actually changed the task state to review: "Auto-moved to review — sub-agent completed PR but didn't call set-review."

Check 2 — Tasks marked "done" with an unmerged/open PR:

curl -sL "${SC_API_URL}/api/tasks/list?status=done" -H "x-api-key: ${SC_API_KEY}"
# Filter to tasks completed in the last 2 hours that have a PR deliverable

For each recently-done task with a PR deliverable, verify the PR is actually merged:

# Extract owner/repo from workspace.repoUrl
# Extract PR number from deliverable URL (e.g. https://github.com/org/repo/pull/123 → 123)
curl -sL -H "Authorization: token ${GITHUB_TOKEN}" \
  "https://api.github.com/repos/${owner}/${repo}/pulls/${PR_NUMBER}" | grep -o '"merged":[^,]*'

If "merged":false (PR still open) → the agent skipped review. Re-open for Hawk.

Idempotency guard before creating a review task:

1. 1. Search existing tasks for one already referencing this PR URL/number in INLINECODE59
2. Only create a new review task if none exists

CODEBLOCK10
Post a warning to the original task thread only when a new review task is created: "⚠️ Task was marked done but PR #N is unmerged. Created review task for Hawk."

Review Dispatch

When review tasks are found, resolve the reviewer deterministically:

1. 1. If SC_REVIEWER_AGENT_ID is set, use it directly
2. Else query agents and pick exact role match INLINECODE61
3. Else fallback to name Hawk or role containing INLINECODE63

CODEBLOCK11

For each review task (has PR deliverable, pickedUpAt not set):

Do NOT call /api/tasks/pickup — the state machine blocks review → working transitions. Instead, spawn the reviewer directly and let them call /api/tasks/review (verdict) which transitions review → done or review → assigned.

Spawn the reviewer agent using the Review Flow template below, passing the task ID and all context directly.

Squad Lead Tasks — Merge & Complete

When the task's assigned agent is the Squad Lead (role contains "Lead" or "Orchestrator"), it means Hawk approved a PR and it's ready to merge. Do NOT just mark it done — merge the PR first.

CODEBLOCK12

If merge fails (conflicts): call /api/tasks/fail with the error — don't force-merge. Post the conflict details to the thread.
If no PR deliverable: just complete the task directly.

---

Concurrency Limit

Before spawning anything, check how many sub-agents are already running:

subagents(action="list")

Count agents with status = "running". The concurrency limit comes from workspace.agentConcurrency (default: 2 if not set).

With a single workspace: If running agents ≥ limit, skip all spawning this cycle and reply HEARTBEAT_OK.

With multiple workspaces (account-level key): Apply the limit per workspace independently. A workspace with agentConcurrency: 3 can have up to 3 agents running regardless of what other workspaces are doing. Group tasks by workspace and check each workspace's running count separately.

Also, never dispatch more than workspace.agentConcurrency tasks per workspace per cron run. The rest will be picked up on the next run.

The workspace owner can change this limit in Squad Control → Settings → Agent Concurrency.

---

Pickup & Dispatch

CODEBLOCK14

Post to the task thread that work is being dispatched:
CODEBLOCK15

Then spawn a sub-agent with the task's agent persona. Include the workspace name in the label so multi-workspace runs are easy to identify:

CODEBLOCK16

Spawn Prompt Template

When building this prompt, resolve workspace config as follows:

• - If task.workspace is present (account-scoped key): use task.workspace.repoUrl, task.workspace.githubToken, INLINECODE79
• If task.workspace is absent (workspace-scoped key): use the top-level workspace from the response

CODEBLOCK17bash
curl -sL -X POST "${SCAPIURL}/api/tasks/set-review" \
-H "x-api-key: ${SCAPIKEY}" -H "Content-Type: application/json" \
-d '{"taskId": "${TASKID}", "agentId": "${AGENTID}", "result": "${summary}", "deliverables": [{"type": "pr", "name": "PR #N", "url": "${PR_URL}"}]}'
CODEBLOCK18

On Completion

1. 1. Post findings/summary to task thread:

   curl -sL -X POST "${SC_API_URL}/api/threads/send" \
     -H "x-api-key: ${SC_API_KEY}" -H "Content-Type: application/json" \
     -d "{\"taskId\": \"${TASK_ID}\", \"agentId\": \"${AGENT_ID}\", \"content\": \"${SUMMARY}\"}"
   

1. 2. Create PR via GitHub API (see references/pr-template.md)
2. If a reviewer agent exists → set task to review:

   curl -sL -X POST "${SC_API_URL}/api/tasks/set-review" \
     -H "x-api-key: ${SC_API_KEY}" -H "Content-Type: application/json" \
     -d "{\"taskId\": \"${TASK_ID}\", \"agentId\": \"${AGENT_ID}\", \"result\": \"${SUMMARY}\", \"deliverables\": [{\"type\": \"pr\", \"name\": \"PR #N\", \"url\": \"${PR_URL}\"}]}"
   

1. 4. If no reviewer → complete directly:

CODEBLOCK21

On Failure

Always report failures — don't silently mark done:

curl -sL -X POST "${SC_API_URL}/api/tasks/fail" \
  -H "x-api-key: ${SC_API_KEY}" -H "Content-Type: application/json" \
  -d "{\"taskId\": \"${TASK_ID}\", \"agentId\": \"${AGENT_ID}\", \"error\": \"description of what went wrong\"}"

---

Review Flow

When routing to a reviewer agent, spawn them with this prompt (fill in all values):

CODEBLOCK23

Note: workspace.githubToken comes from the /api/tasks/pending or /api/tasks/pickup response. Never read it from a credentials file — it may not exist on this machine.

---

Discovering Agents

CODEBLOCK24

Reviewer selection order:

1. 1. SC_REVIEWER_AGENT_ID (explicit override)
2. Exact INLINECODE87
3. Fallback role contains Reviewer or name INLINECODE89

Poll Script Tests

Run parser tests locally:

CODEBLOCK25

INLINECODE90 envelope contract is documented in:

• - INLINECODE91

Creating Tasks Programmatically

CODEBLOCK26

---

Common Mistakes

1. 1. Marking done without doing work — Always post results to the thread and create a PR (if code task) before marking complete. Empty result + no thread messages = task wasn't really done.
2. Sub-agent calling /complete instead of /set-review after opening a PR — This is the most common workflow violation. If a PR was opened, the ONLY valid next call is set-review. Calling complete directly skips code review entirely and leaves an unmerged PR dangling. The stuck task recovery check now catches "done" tasks with open PRs and auto-creates a Hawk review task.
3. Squad Lead skipping the merge — When a task is assigned to the Squad Lead and has a PR deliverable, merge the PR to main BEFORE marking complete.
4. Not passing SCAPIURL/SCAPIKEY into spawn prompt — Sub-agents can't call back to Squad Control without these. Always include them in the spawn template.
5. Not using workspace.repoUrl — The pending and pickup responses include workspace.repoUrl and workspace.githubToken. Use them — don't assume a default repo path.
6. Forgetting to report failure — If something goes wrong, call /api/tasks/fail. Tasks stuck in "working" forever block the queue.
7. Cloning without token on private repos — Check workspace.githubToken and use the git credential helper: git -c "credential.helper=!f() { echo username=x-access-token; echo password=<token>; }; f" clone "$REPO_URL" — never embed the token directly in the URL as it can leak via process lists, git remotes, or logs.
8. Not pulling latest before branching — Creates PRs against stale main, causing merge conflicts.
9. Applying global concurrency instead of per-workspace — When handling tasks from multiple workspaces (account-level key), each workspace has its own agentConcurrency limit. Don't count agents running for workspace A against workspace B's limit.
10. Ignoring task.workspace and always using top-level config — Account-level keys embed workspace config directly in each task. If task.workspace is present, use it; fall back to the top-level workspace only when it's absent.