wander（wander 开发）

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:

Trigger  →  Task runs remotely  →  Result
(Agent)     (can't speed up)       (Agent + User both need to know)

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. 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. Never assume success — a background monitor starting is not the same as the task succeeding.

# After Wander background process exits, check result:
gh run view <RUN_ID> --json conclusion -q .conclusion
# → "success" | "failure" | "cancelled" | "timed_out"

# If failure, fetch logs for Agent to diagnose:
gh run view <RUN_ID> --log-failed

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

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)
• gh workflow run (manual dispatch)
• eas build that is backed by a GHA wrapper

Steps:

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
• jq installed
• Wander on disk: WANDER_HOME (default ~/code/wander)
• macOS for notification center; Linux/headless: output-only mode still works

Install

git clone https://github.com/ERerGB/wander.git ~/code/wander
cd ~/code/wander && chmod +x *.sh

Add to shell rc:

export WANDER_HOME="${WANDER_HOME:-$HOME/code/wander}"
export PATH="$WANDER_HOME:$PATH"
alias wf='watch-workflow.sh'
alias wfbg='watch-workflow-bg.sh'
alias wfdt='watch-workflow-detached.sh'

Picking the right mode

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:

workflows:
  - name: "ci.yml"
    description: "Lint + unit tests"
    check_window: 180      # grace window if already finished when we start
    expected_duration: 45  # typical runtime
    category: "smoke"

  - name: "build.yml"
    description: "Docker build + push"
    check_window: 600
    expected_duration: 180
    category: "build"

  - name: "deploy.yml"
    description: "Railway deploy"
    check_window: 900
    expected_duration: 300
    category: "deploy"

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:

cd /path/to/repo
"$WANDER_HOME/scripts-registry.sh" scan-workflows --auto-scope

Default check_window when unconfigured: 300s.

Canonical usage patterns

After any git push

git push origin main && "$WANDER_HOME/watch-workflow-bg.sh" ci.yml

With project wrapper (recommended for teams)

# scripts/watch-ci.sh
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
WANDER_DIR="${WANDER_HOME:-$(dirname "$REPO_ROOT")/wander}"
exec "$WANDER_DIR/watch-workflow-bg.sh" ci.yml "$@"

Then: git push && ./scripts/watch-ci.sh

EAS mobile build (via GHA wrapper)

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

git push origin feat/my-branch && "$WANDER_HOME/watch-workflow-bg.sh" eas-build.yml

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

Manual workflow dispatch

gh workflow run deploy.yml --ref main
"$WANDER_HOME/watch-workflow-bg.sh" deploy.yml main

Edge cases

When a task fails

# View failed step logs
gh run view <RUN_ID> --log-failed

# Re-run only failed jobs
gh run rerun <RUN_ID> --failed

WANDER_HOME resolution

1. $WANDER_HOME env var
2. Sibling of current repo: $(dirname "$REPO_ROOT")/wander
3. Default: ~/code/wander

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. 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
• EDGE_CASES.md
• COFFEE_BREAK.md