goal-relay

name	goal-relay
description	Use when a goal-mode Codex task reaches a long-running wait, experiment monitor, heartbeat automation, external-state dependency, or token-burning auto-continuation loop.

Goal Relay

Overview

Goal Relay is the handoff pattern for long-horizon work: use an active goal while doing real work, then relay the waiting phase to a sparse heartbeat automation so Codex does not burn tokens by constantly continuing the goal.

The parent objective stays alive in the automation prompt. The active goal is only for the current execution phase.

Source Rationale

Codex goal continuation is eager by design:

• core/src/goals.rs can start a hidden continuation turn through MaybeContinueIfIdle.
• app-server/src/request_processors/thread_lifecycle.rs calls continue_active_goal_if_idle() after a running-thread resume when goal updates are emitted.
• core/templates/goals/continuation.md tells the model to keep the full objective active and continue working unless completion is proven.

That is correct for active work, but bad for long waits. A heartbeat that resumes a thread can become another active-goal continuation trigger unless the goal has been relayed out of active state.

When To Use

Use this when:

• A user asks Codex to run an experiment, training job, benchmark, crawl, CI job, data build, or other long-running process.
• The next useful action depends on external time or external state.
• The task needs periodic monitoring, debugging, or improvement.
• Goal mode is active and heartbeat or recurring automation will be used.
• Codex is repeatedly waking to "check" a process more often than the process can produce meaningful new evidence.

Do not use this for:

• Short operations where the next step should happen in the same turn.
• Tasks where Codex can complete verification now.
• Pure reminders with no active goal or long-running process.

Core Rule

Never leave an active goal open just to wait.

When the task enters a monitoring phase:

1. Verify that the real work is actually running or queued.
2. Create or update a heartbeat automation for sparse monitoring.
3. Put the original objective, current state, evidence paths, and re-goal rules into the automation prompt.
4. Mark the current execution goal complete after the handoff is installed.
5. On a later heartbeat, create a new goal only when real work is needed again.

Do not claim the parent objective is finished unless it is. Say that the current execution phase was completed by launching the work and handing monitoring to automation.

Cadence

Choose the interval from expected signal rate, not anxiety.

Situation	Default cadence
Failure likely soon, logs changing fast	10-15 minutes
Normal experiment, benchmark, build, or eval	30 minutes
Multi-hour training or data generation	1-2 hours
Overnight or multi-day run	4-12 hours
Daily external dependency	Daily

Use a faster cadence only when a faster check can change the next action.

Handoff Checklist

Before ending the active goal, confirm:

• The command, job, service, or external process is real. Do not mock it.
• There is authoritative evidence to inspect later: log path, output directory, process id, run id, dashboard URL, queue id, test command, or status command.
• The next monitor prompt can recover context without relying on hidden conversation memory.
• The heartbeat is attached to this thread when the user wants this thread to continue.
• The heartbeat prompt says when to stay quiet or brief, when to debug, when to create a new goal, and when to declare final completion.
• Existing matching automations were updated instead of duplicated.

Heartbeat Prompt Shape

Write heartbeat prompts as self-contained runbooks:

Parent objective:
<the user's full long-horizon objective>

Current state:
<what was launched, when, where, and by which command>

Workspace:
<absolute cwd and important repo/worktree notes>

Evidence to inspect:
- <log/status command/output path/run id>
- <success artifact or verifier>
- <failure signals>

Monitoring cadence:
<why this interval is appropriate>

On each heartbeat:
1. Inspect the authoritative current state before reasoning from memory.
2. If nothing material changed, keep the response short and do not create a goal.
3. If a small fix or restart is needed, do it directly if safe, then keep monitoring.
4. If long-horizon work is needed, create a new goal that combines the parent objective with the current evidence, work until the next waiting phase or final completion, then relay again.
5. If final success is proven, report the evidence and stop or update the automation as appropriate.

Tool Pattern

Prefer a heartbeat automation for continuing the current thread. In Codex app environments, use the automation tool rather than writing raw scheduler files.

For a thread-attached monitor:

mode: create or update
kind: heartbeat
destination: thread
rrule: FREQ=MINUTELY;INTERVAL=30
name: Monitor <specific run>
prompt: <self-contained runbook>
status: ACTIVE

Use a cron automation only for detached workspace jobs where a standalone run is clearly better than continuing this thread.

Re-Goal Rules

A heartbeat should create a new goal only when the next phase needs sustained Codex work, for example:

• A run failed and needs diagnosis, code changes, restart, and verification.
• Intermediate results are ready and need analysis, report generation, or follow-up experiments.
• The monitor found that the original approach is stuck and needs a new plan.
• Final verification requires multiple steps that should not be squeezed into a monitor check.

The new goal objective should include:

• The parent objective.
• The current evidence and failure/success state.
• The concrete next deliverable.
• The rule to relay again when the task reaches another external wait.

Completion Wording

When closing the active goal at handoff, be precise:

• Good: "The execution phase is complete: the experiment is running, logs are at X, and heartbeat monitoring is installed every 30 minutes."
• Bad: "The experiment objective is complete" when the final result is still pending.

If goal tooling only supports complete, use it for the completed execution phase after the heartbeat is installed. Do not use final-answer wording that misrepresents the parent objective.

Common Mistakes

• Leaving goal mode active while waiting for a process to finish.
• Running sleep loops or frequent manual checks instead of using automation.
• Creating a heartbeat without the original objective and evidence paths.
• Creating duplicate automations instead of updating the existing monitor.
• Starting a new goal for every heartbeat even when no action is needed.
• Marking the parent objective complete just because the monitor was installed.
• Using an unrealistically fast interval that cannot produce new signal.