feat: add agent-friendly RunPane workflow commands

[parsakhaz]

Intent

RunPane now has the core agent-control primitives: agents can create panes, inspect panels, send terminal input, wait for readiness, and read bounded terminal output. The next step is to make the CLI feel purpose-built for agent workflows instead of requiring agents to manually compose many low-level commands every time.

The goal is to add a higher-level, agent-friendly CLI layer for common workflows like "start a Codex/Claude pane for this GitHub issue", "set up a small issue loop", and "observe whether the panel is ready, blocked, waiting for input, or actively working". This should reduce turns, improve reliability, and make Pane's open-source, agent-agnostic, cross-OS workflow feel obvious to both human users and automation.

Scope

Add opinionated RunPane CLI workflows on top of the existing low-level pane/panel primitives.

The work should include:

• A general health/discovery command such as runpane doctor that tells an agent whether Pane is reachable, which app/CLI versions are involved, whether it is crossing a WSL/Windows boundary, and what transport/path it is using.

• A high-level single-issue workflow command, for example:

  runpane issue start https://github.com/dcouple/Pane/issues/235 \
    --repo dcouple/Pane \
    --agent codex \
    --skill discussion \
    --wait-ready \
    --json

  The exact command shape can change, but the outcome should be one command that creates the pane/worktree, starts the requested agent, sends the intended initial prompt, waits for readiness, and returns a compact validation summary.

• A high-level multi-issue/loop bootstrap command, for example:

  runpane loops start \
    --repo dcouple/Pane \
    --issues 235,222,260 \
    --agent codex \
    --skill discussion \
    --wait-ready \
    --json

  This should create one pane per issue, validate each agent start, and summarize what is ready, stuck, or still initializing.

• A richer observation command such as runpane panels observe --panel <id> --json that returns signal rather than raw terminal dump:

  • clean bounded recent output
  • process/panel state if known
  • whether output appears idle, busy, waiting for input, or stuck on a known prompt
  • any detected known prompt, such as an agent upgrade prompt
  • suggested next CLI command when there is an obvious safe next action

• Better interactive prompt handling for common agent CLI prompts. At minimum, detect known update/upgrade prompts and return structured state like waiting_for_input, detectedPrompt, and safeActions rather than forcing agents to scrape terminal text.

• More opinionated tool schema/docs recipes so agents know the preferred flows:

  • create one issue pane
  • create multiple issue panes
  • recover from a stuck update prompt
  • control Windows Pane from WSL
  • read output with context-safe limits
  • send input safely

Keep the existing low-level primitives available. The goal is to add a workflow layer, not replace the lower-level commands agents need for recovery and debugging.

Starting Points

This is a follow-up to the RunPane CLI/API expansion work:

• Prior broad CLI/API issue: feat: expand runpane CLI and local Pane API surface #248
• Recent agent-control release: v2.3.8
• Existing primitives to build on:
  • runpane panes create
  • runpane panels screen
  • runpane panels submit
  • runpane panels wait
  • runpane agents doctor

Non-exhaustive code starting points:

• main/src/ipc/runpane.ts
• main/src/ipc/runpane.test.ts
• shared/runpane-contract.json
• scripts/generate-runpane-contract.ts
• packages/runpane/src/generated-contract.ts
• packages/runpane-py/src/runpane/generated_contract.py
• agent context / managed AGENTS.md generation code, if recipes should be exposed there too

Treat these as starting points and inspect current main before implementing.

Acceptance Criteria

• runpane doctor --json provides a concise machine-readable health summary for agents, including app reachability, CLI/app version compatibility, and WSL/Windows boundary hints when applicable.
• A single command can start an agent for one GitHub issue in the chosen repository, wait for readiness, and return pane id, panel id, status, output preview, validation results, and suggested next commands.
• A single command can bootstrap a small multi-issue loop, creating one pane per issue and returning a compact per-issue status table/JSON result.
• The CLI validates that prompts were actually delivered and that the target panel appears started, blocked, waiting, or ready instead of only reporting that a command was dispatched.
• Observation output is context-safe by default: bounded, cleaned, and summarized enough for agents, with explicit options to fetch more detail only when needed.
• Known interactive prompts are surfaced structurally where feasible, with safe actions described for agents.
• Tool schemas and agent-facing docs include recipe-level guidance for the new workflows, including WSL controlling Windows Pane.
• Existing low-level commands remain stable and documented for fallback/recovery use.
• Tests cover the new workflow commands, validation responses, bounded output behavior, and at least one known interactive prompt detection case.

Inputs Needed

• Final command names are open. Suggested shapes are runpane issue start, runpane loops start, runpane panels observe, and runpane doctor, but implementation should choose names that fit the existing CLI grammar.
• Decide whether GitHub issue expansion should accept only URLs initially or also owner/repo#123, #123, and comma-separated issue numbers.
• Decide whether --skill discussion should map to literal prompt prefixes like $discussion <issue-url> or a more generic template system.

Notes

The CLI should assume agents are not deeply familiar with Pane. Responses should be explicit, compact, and action-oriented. Less is more by default: return enough information for the agent to validate and choose the next action, but avoid dumping full terminal scrollback unless specifically requested.

The ideal response after a successful issue start should look roughly like:

{
  "ok": true,
  "pane": { "id": "...", "name": "Issue #235 discussion" },
  "panel": { "id": "...", "kind": "terminal", "agent": "codex" },
  "status": "ready",
  "validation": {
    "processStarted": true,
    "promptDelivered": true,
    "lastOutputPreview": "Codex is reviewing issue #235..."
  },
  "next": {
    "observe": "runpane panels observe --panel ... --json",
    "sendInput": "runpane panels submit --panel ... --text '...' --yes --json"
  }
}