AgentWire Scheduler & Overnight Queue

Scheduler Task Gates

Tasks in ~/.agentwire/scheduler.yaml can define gate preconditions to skip execution when changes aren't relevant:

yaml
1tasks:
2  code-quality:
3    gate:
4      git_commit: true  # Skip if HEAD unchanged since last run
5  doc-drift:
6    gate:
7      git_diff:         # Skip if no commits touched these paths
8        - docs/
9        - agentwire/
10  custom-check:
11    gate:
12      command: "test -f /tmp/ready.flag"  # Skip if command exits non-zero

Gates are evaluated before dispatching and skip the task (zero AI cost) if conditions fail. Multiple gates are AND'd. Gates fail open on errors. See docs/missions/completed/master-ralph-loop.md for details.

Scheduler Task Scheduling

Each task has a schedule field (replaces the old interval). The scheduler uses _compute_next_eligible() as the single source of truth for when a task becomes eligible.

schedule field reference:

Must have at least every OR after (or both).

Examples:

yaml
1# Duration-based interval
2schedule:
3  every: 4h
4
5# Time-anchored daily
6schedule:
7  every: day
8  at: "08:00"
9
10# Dependency with delay
11schedule:
12  after: upstream-task
13  delay: 1h
14  cooldown: 3h
15
16# Weekend exclusion
17schedule:
18  every: 4h
19  except: [saturday, sunday]

Restart safety: last_dispatch is persisted before running. Tasks dispatched within 2h are considered "in-flight" and won't be re-dispatched after restart.

Scheduler Task Priority

Tasks sort by priority first (lower = runs first), with overdue score as tiebreaker. This ensures pipeline ordering — upstream stages run before downstream when multiple tasks are overdue.

Tasks with default priority (99) sort after all prioritized tasks. Fillers always run after all regular tasks regardless of priority.

Workflow-Backed Tasks

A scheduler task can dispatch a pi workflow DAG (Phase 3) instead of shelling out to agentwire ensure. Use workflow: + inputs: on the task; omit session: and task:. Workflow tasks run in-process via agentwire.workflows.runner.run_workflow, bypass tmux entirely, and write their run under ~/.agentwire/workflows/runs/<run_id>/.

yaml
1tasks:
2  nightly-doc-audit:
3    schedule: { every: day, at: "23:00" }
4    workflow: doc-drift-check        # workflow name or absolute YAML path
5    inputs:
6      paths: "docs/,agentwire/"
7      context: "{{ project }}"       # {{ task }}, {{ project }}, {{ session }}, {{ workflow }} expand from scheduler context
8    gate:
9      git_diff: [docs/, agentwire/]  # git gates still need `project:`
10    project: /Users/dotdev/projects/agentwire-dev
11    max_runs: 30

Status mapping: workflow success → complete, partial → incomplete, failure → failed. Node-level detail is included in the task_completed event (workflow, run_id, nodes[]) and rendered in agentwire scheduler report --artifact.

Dry-run: agentwire scheduler run <name> --dry-run prints the workflow plan without touching state — workflow tasks only.

Rule: a task must set either task: (ensure path) or workflow: (DAG path), not both. inputs: is only valid with workflow:. Git gates (git_commit, git_diff) require project: to be set regardless of dispatch path.

One-Time and Limited Tasks

Tasks can auto-disable after a set number of runs:

yaml
1tasks:
2  tonight-scaffold:
3    # ...
4    once: true        # Run once, then auto-disable (shorthand for max_runs: 1)
5    schedule:
6      every: 1m       # Run ASAP
7
8  quarterly-report:
9    # ...
10    max_runs: 4       # Run 4 times then auto-disable
11    schedule:
12      every: day
13      at: "09:00"

• once: true — shorthand for max_runs: 1
• max_runs: N — auto-disables task after N successful dispatches
• Scheduler logs a task_disabled event with reason: max_runs_reached
• Re-enabling a disabled task via agentwire scheduler enable <name> resets it

Overnight Session System

"Prepare once, fork many, execute overnight." Human prepares sessions interactively during the day (full back-and-forth with Claude), queues them, and the orchestrator dispatches them during off-hours with draft PR creation.

User workflow:

5:00 PM — Open session, discuss project context with Claude
5:15 PM — agentwire overnight prepare --from piinpoint --task "refactor payment module"
           → Queued. Session context captured.
5:16 PM — Repeat for more tasks
5:43 PM — Go home.

10:00 PM — Orchestrator dispatches session 1 → works → PR created
11:00 PM — Dispatches session 2 → works → PR created
12:00 AM — All done. Voice notification sent.

8:00 AM — agentwire overnight report → review draft PRs

Queue directory: ~/.agentwire/overnight/ (active items), ~/.agentwire/overnight/done/ (archived)

How it works:

1. prepare captures: Claude sessionId (for --resume --fork-session), git branch, HEAD commit
2. dispatch creates tmux session, launches agent with forked context, creates work branch
3. On completion: auto-commit, push, draft PR, archive, notify
4. Orchestrator respects work window (default 22:00-07:00)

Session type: Uses claude-auto by default for classifier safety net. Override with --type.