Wander — Async Task Completion Monitor

Don't watch. Wander. The core philosophy: when you trigger something async, you should be notified when it finishes — not polling, not refreshing, not waiting.

Mental model (first principles)

Every async task has the same shape:

CODEBLOCK0

Wander owns the middle-to-right transition. The Agent triggers and moves on. Wander closes the loop back to both the user (notification) and the Agent (result context).

The loop is only complete when the Agent knows the result. After Wander reports completion, the Agent must:

1. 1. Read the terminal output from the Wander background process to get the actual result.
2. Act on the result — do not consider the task "done" until the result is confirmed:

- ✅ success → proceed to next step (e.g., announce PR ready, deploy, tag release) - ❌ failure → immediately surface the failure, fetch failed logs, propose fix

1. 3. Never assume success — a background monitor starting is not the same as the task succeeding.

CODEBLOCK1

Task taxonomy — what counts as a "task" Wander should monitor:

Task type	Examples	Wander support
CI test	lint, unit test, e2e	✅ Native (GitHub Actions)
Build

Docker, web bundle | ✅ Native (GHA build.yml) |
| Mobile build | EAS iOS/Android | ⚠️ GHA wrapper only (not EAS CLI direct) |
| Deploy | Railway, Fly, Vercel | ✅ Native (GHA deploy workflow) |
| Release / publish | npm, ClawHub, App Store | ✅ Native (GHA publish workflow) |
| Ad-hoc long task | DB migration, data job | ⚠️ Manual: wrap in GHA workflow_dispatch |

Current engine: GitHub Actions only. For EAS builds triggered via eas build CLI, Wander cannot monitor directly — use a GHA wrapper workflow that calls EAS, then monitor that workflow.

For the full v1 scope statement (GHA vs non-GHA CLIs, workarounds, roadmap links), see the repository README: v1 scope: GitHub Actions today.

---

Agent auto-trigger (mandatory)

After triggering ANY async task that maps to a GitHub Actions workflow, start Wander in background mode unless the user opts out.

Trigger signals to watch for:

• - git push to a branch that has CI/CD configured
• PR created or merged (if deploy workflow triggers on merge)
• INLINECODE3 (manual dispatch)
• INLINECODE4 that is backed by a GHA wrapper

Steps:

1. 1. Check if .workflows.yml exists → use it to pick the right workflow name and timing.
2. If .workflows.yml is absent but .github/workflows/ exists → run scan_workflows (or ask user) to identify the right workflow, then start.
3. Use watch-workflow-bg.sh <workflow.yml> — always background unless user explicitly wants to block.
4. After ~8s check terminal output and report initial status.
5. Tell the user: "Wander is watching <workflow>. I'll notify you when it finishes — continue working."
6. Poll for result: periodically check the terminal output file or run gh run view <RUN_ID> --json conclusion. Do not declare the task complete until conclusion is success.
7. On result:

- success → report to user, proceed with next planned step
- failure → immediately fetch gh run view <RUN_ID> --log-failed, surface the error, propose a fix

If .github/workflows/ does not exist: offer monitoring but do not auto-start.

---

When to use this skill

• - User triggers anything async that will take > 30 seconds
• User says "let me know when CI is done" / "notify me when the build finishes"
• User is about to wait or refresh manually
• Long pipelines: E2E, mobile build wrappers, release publish, DB migrations via GHA
• Any git push that touches a branch with a workflow on: push trigger

When NOT to use

• - Task completes in < 10 seconds (just wait inline)
• No GitHub Actions involved and no GHA wrapper exists
• User explicitly said they want to watch synchronously

---

Prerequisites

• - gh CLI installed and authenticated
• INLINECODE18 installed
• Wander on disk: WANDER_HOME (default ~/code/wander)
• macOS for notification center; Linux/headless: output-only mode still works

Install

CODEBLOCK2

Add to shell rc:

CODEBLOCK3

---

Picking the right mode

Mode	Script	Use case
Background	INLINECODE21	Default. Keep working; get notified.
Detached

watch-workflow-detached.sh | Close terminal; logs to ~/.wander_logs/ |
| Foreground | watch-workflow.sh | Block session until done (rare) |

Rule of thumb: always background. Switch to detached for >5 min tasks where you'll close the terminal.

---

Workflow registry (.workflows.yml)

Each workflow has different timing. The registry tells Wander what to expect:

CODEBLOCK4

check_window = if the workflow already finished by the time Wander starts, how far back should we still accept it as "the run we triggered"? Set this to ~6x expected_duration.

Auto-generate for a repo:
CODEBLOCK5

Default check_window when unconfigured: 300s.

---

Canonical usage patterns

After any git push

CODEBLOCK6

With project wrapper (recommended for teams)

CODEBLOCK7

Then: INLINECODE29

EAS mobile build (via GHA wrapper)

If your EAS build is triggered by a GHA workflow (e.g. eas-build.yml):

CODEBLOCK8

If EAS is triggered directly via CLI (no GHA), Wander cannot monitor it natively — consider creating a workflow_dispatch wrapper.

Manual workflow dispatch

CODEBLOCK9

---

Edge cases

Scenario	Behavior
Workflow finishes before Wander starts	Detected via check_window; instant result + notify
Run not appearing after 30s

Wander waits up to 30s, then exits with tips |
| Wrong branch filter on workflow | No run found; Wander reports and exits |
| Very short workflow (<30s) | Fast path: check_window catches it immediately |
| Very long workflow (>10min) | Use detached mode; logs survive terminal close |

---

When a task fails

CODEBLOCK10

---

WANDER_HOME resolution

1. 1. $WANDER_HOME env var
2. Sibling of current repo: INLINECODE35
3. Default: INLINECODE36

---

Known limitation: non-GHA tasks

Wander v1 is GitHub Actions-native. For tasks outside GHA (EAS CLI, Railway CLI, custom scripts), the correct pattern is:

1. 1. Wrap the task in a GHA workflow_dispatch workflow.
2. Trigger via gh workflow run.
3. Monitor with Wander.

A future version may support pluggable backends (EAS, Railway, etc.) via a task adapter layer.

---

Reference

• - Wander README
• EDGECASES.md
• COFFEE_BREAK.md