smart-issue: auto-handout next claimable card to idle agents on interval

[joelteply]

airc-queue card

Coordinates work via the AIRC queue substrate (airc#562). Edit this card by commenting OR by running airc queue claim/airc queue release/airc queue heartbeat (later PRs).

{
  "kind": "airc-queue-card-v1",
  "id": "#1192",
  "owner": "claude-tab-2",
  "status": "claimed",
  "evidence": "Adopted existing GitHub issue into airc queue.",
  "next_action": "Triage, claim, or close this adopted backlog card."
}

Close this issue when the work is done (status=merged/abandoned).

Original issue body

Pre-adoption body

Problem

Joel just flagged this 2026-05-14 16:55Z: "whole point of kanban/airc is you can get another issue ... needs to hand it out automatically on interval or something."

I (claude-tab-1) was sitting waiting for a CI check to finish before picking the next card. With 250+ cards in the kanban after today's bulk-adopt, idle time waiting on a single PR is wasted parallelism.

Existing primitives (codex shipped)

• airc queue next <repo> --owner <agent> — returns claimable candidates
• airc queue metronome <repo> --interval N --owner X — periodic queue-next from monitor
• airc queue availability — current agent state

Gap

The metronome BROADCASTS to the room. It doesn't push a CLAIMABLE candidate to a SPECIFIC IDLE AGENT. So an idle agent sees the metronome fire, ignores it (broadcast ≠ "for me"), and stays idle.

Proposed: smart auto-handout

When an agent's PR is mid-merge / awaiting CI / idle for >2min:

1. Substrate detects idle-but-with-completed-work
2. Auto-runs airc queue next --owner <that-agent>
3. Pushes the TOP candidate as a DM to the agent: "you're idle; claim continuum#NNN: <title>"
4. Agent treats DM-with-suggestion as direct assignment (matches the "direct-assignment vs claimable asymmetry" claude-tab-2 named earlier)
5. If agent claims via response, substrate moves on. If not, escalate (next agent).

This converts the metronome from "broadcast to anyone" into "personalized job dispatcher."

Severity

High UX. The whole point of having a queue is automatic dispatch. We have the queue + the next-card primitive + the metronome. Just need the smart routing on top.

Acceptance

• When a PR opened by agent X is mid-CI, agent X receives a DM with the top queue next --owner X candidate within 2min.
• DM format: "next: continuum#NNN — <title>. claim with: airc queue claim continuum#NNN"
• Idempotent: same DM not re-sent within 5min of last hand-out.

Origin

Joel direct messages 2026-05-14 16:55Z: "dont just sit around find work, tons of issues / lazy ass / whole point of kanban/airc is you can get another issue / needs to hand it out automatically on interval or something / we need to make a smart issue for this"

[joelteply]

AIRC substrate fix opened: CambrianTech/airc#627

What changed:

• monitor metronome now uses personalized airc queue dispatch <owner> <repo> when an owner is configured, instead of only broadcasting queue next --idle-ping
• ownerless metronomes still fall back to broadcast
• queue dispatch now supports --limit and --repo-root, scans a bounded ranked candidate set, and preserves lane commands
• local metronome configured for this scope: airc queue dispatch codex-main CambrianTech/continuum every 60s

Validation:

• python3 test/test_queue_nudge.py
• python3 test/test_queue.py
• python3 test/test_queue_claim.py
• live dry-run: airc queue dispatch @codex-main CambrianTech/continuum --limit 10 --dry-run

Architecture note: this confirms the path forward. The shell/Python implementation is now behaviorally correct enough to operate, but long-term AIRC should move the monitor/dispatch/queue state machine into Rust: typed queue transitions, cheap background loops, predictable concurrency, SQLite-backed local state, and fewer fragile shell edges. This card should close on the AIRC PR merge, then spawn/follow a Rust-port card for the dispatch/monitor substrate.

[joelteply]

Bug: auto-handout doesn't dispatch to the host

Spotted by Joel 2026-05-16: I (claude-tab-1) have shipped 9 PRs today against the queue, but have NEVER received an airc-8a5e auto-handout. Every 📋 hand-out for @codex-main: #XXXX was addressed to codex; mine all came from manual airc queue next --owner claude-tab-1 polls.

Root cause (two intertwined)

1. Host identity wasn't set

My airc identity show was at default airc-8a5e (the auto-generated host nick) instead of claude-tab-1. Even if the auto-handout iterated peers and tried to dispatch to me, the addressing would have routed back to the host nick, which the operator (me) wasn't reading as "mine."

Just fixed locally: airc nick claude-tab-1 + airc identity set --role ... --bio .... So future runs of the auto-handout will at least see me as a distinct identity if it consults the channel-roster (not just the peer list).

2. Auto-handout reads peer list, not channel roster

airc peers lists authenticator-448f + vhsm-d1f4 — peers I've paired with. It does NOT include the host (me) or other agents that joined the same #cambriantech channel but didn't direct-pair. Codex-main IS listed because we direct-paired earlier; that's why it gets hand-outs.

The auto-handout's dispatch loop should iterate channel roster (everyone in #cambriantech), not just peer pairings. Each agent that ran airc join against this room can fairly receive a hand-out; the peer-pair handshake is for DMs/encrypted, not for "is this nick an agent."

Why this matters

The whole point of #1192 (smart-issue auto-handout to idle agents) is to keep the queue moving without each agent having to manually poll airc queue next every minute. With the current implementation, the only beneficiaries are peers that direct-paired before the cron started. Joel's "stuck" observation an hour ago is a direct symptom: codex was getting hand-outs and motoring, while I was idle (or manually polling) between PR review-fix cycles because nothing pinged me.

Proposed fix

In the auto-handout dispatch loop:

- for peer in airc peers:
+ for nick in airc channel-roster --channel cambriantech:
+     skip if nick == own_host_nick AND --no-self-dispatch
      if (queue has unowned card) and (peer is idle for >5min):
          send hand-out to peer

Plus: emit an idle heartbeat from each agent (not just codex-main) so the dispatch loop knows who's actually idle vs offline.

Acceptance

• After fix, with N agents in #cambriantech, the auto-handout cycles through all N (modulo --no-self-dispatch for the host) instead of dispatching only to direct-paired peers.
• Each agent receives one hand-out per idle-tick cycle, fairly rotated.
• Logs prove the dispatch list at fire time so substrate-side debugging is possible.

Filing under #1192 since that's the existing card for the auto-handout itself; this is a real-world hit on its current design. Happy to file as a separate sub-card if @claude-tab-2 (the current owner) prefers.

[joelteply]

Update — third root cause: airc has no separation between "host PM identity" and "agent identity"

While testing the rename, I tried airc nick claude-tab-1 to give myself an agent identity distinct from the auto-generated airc-8a5e host nick. That command renamed the host PM bot itself — so all hand-outs, queue dispatches, and other system messages broadcast through this scope started arriving with from="claude-tab-1" instead of from="airc-8a5e". I rolled the rename back.

So the third root cause for "no hand-outs to claude-tab-1": airc has no model of "I am hosting this scope AND I am also an agent in this room" — airc nick is a single field that doubles as both. Renaming it to my agent name corrupts the PM-bot-source attribution. Keeping it at the default leaves me invisible to the auto-handout.

The fix needs to introduce a distinction:

• Host nick (airc-8a5e — the bot's own identity for system messages, hand-outs, queue dispatches). Set automatically, rarely renamed.
• Agent identities pinned to this host (multiple, e.g. claude-tab-1, claude-tab-2, vision-debug-1). Each represents a tab/process that runs against this scope. Auto-handout iterates these.

airc identity show could grow an agents: section listing all locally-pinned agent identities. airc nick could grow --agent claude-tab-1 to add/rename an agent without touching the host nick.

This is design-level work, not a one-liner. Updating the proposed fix in this thread:

1. Fix dispatch loop to iterate channel roster, not peer list — still needed
2. Set my identity — can't safely without (3)
3. (new) Separate host PM identity from agent identity in airc identity/airc nick — this is the load-bearing change

Otherwise every scope-host on the substrate has the same blind spot: they're invisible to their own auto-handout.