leek/agent-skills / skills/autopilot
autopilot
VerifiedBuild a whole spec while you are away. Asks every question up front, then a runner drives parallel fresh top-level Claude Code, Codex, or Grok sessions, one per ticket in its own worktree, onto one integration branch, delivered as one PR or a stack of PRs.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.5 KB |
| agents/openai.yaml | config | 264 B |
| references/worker.md | markdown | 9.7 KB |
| scripts/autopilot.shexecutable | script | 13.5 KB |
| scripts/land.shexecutable | script | 6.2 KB |
| scripts/lib/observer.sh | script | 9.9 KB |
| scripts/lib/output.sh | script | 2.4 KB |
| scripts/lib/process.sh | script | 5.0 KB |
| scripts/lib/provider.sh | script | 12.2 KB |
| scripts/lib/runner.sh | script | 33.5 KB |
| scripts/lib/state.sh | script | 7.9 KB |
| scripts/lib/tickets.sh | script | 6.9 KB |
| scripts/lib/tmux.sh | script | 7.5 KB |
| scripts/result-schema.json | config | 526 B |
| scripts/test-land.sh | script | 4.4 KB |
| scripts/test-root-key.shexecutable | script | 8.6 KB |
| scripts/test-run.sh | script | 12.7 KB |
| scripts/test-tmux.shexecutable | script | 10.6 KB |
scripts/lib/runner.sh
View on GitHub#!/bin/bash
# Stateful Autopilot run loop: a parallel frontier of fresh top-level worker processes, each
# build worker in its own worktree, landing on one integration branch; then one finish worker.
set -e
RUN_STAGE="build"
DISPATCH_NEEDED="true"
DRAINING="false"
LIMIT_REACHED="false"
FINISH_RAN="false"
FINISH_STATUS=""
FINISH_REASON=""
FINISH_NEXT_REF=""
FINISH_MERGED=""
RELEASED_LIST=""
BLOCKED_LIST=""
FAILED_LIST=""
QUESTIONS=""
BLOCKERS=""
FAILURE_REASON=""
CLAIM_REASON=""
TERMINAL_STATUS=""
TERMINAL_NEXT_REF=""
TERMINAL_REASON=""
TERMINAL_EXIT=0
NEXT_HEARTBEAT=0
BOARD_LINES_SEEN=0
find_skill() {
local name="$1"
local candidate=""
local user_home="${HOME:-}"
local codex_home="${CODEX_HOME:-}"
local grok_home="${GROK_HOME:-}"
local roots=("$REPO_ROOT/.agents/skills" "$REPO_ROOT/.claude/skills" "$REPO_ROOT/.codex/skills" "$REPO_ROOT/.grok/skills")
roots+=("$(cd "$SKILL_DIR/.." && pwd -P)")
if [[ -n "$user_home" ]]; then
roots+=("$user_home/.agents/skills" "$user_home/.claude/skills")
[[ -n "$codex_home" ]] || codex_home="$user_home/.codex"
[[ -n "$grok_home" ]] || grok_home="$user_home/.grok"
fi
[[ -z "$codex_home" ]] || roots+=("$codex_home/skills")
[[ -z "$grok_home" ]] || roots+=("$grok_home/skills")
for candidate in "${roots[@]}"; do
if [[ -f "$candidate/$name/SKILL.md" ]]; then
(cd "$candidate/$name" && printf '%s/SKILL.md\n' "$(pwd -P)")
return 0
fi
done
return 1
}
resolve_workflow_skills() {
local setup_path
IMPLEMENT_SPEC_PATH="$(find_skill implement-spec)" || runner_failure "required skill not found: implement-spec"
IMPLEMENT_PATH="$(find_skill implement)" || runner_failure "required skill not found: implement"
TO_TICKETS_PATH="$(find_skill to-tickets)" || runner_failure "required skill not found: to-tickets"
setup_path="$(find_skill setup)" || runner_failure "required skill not found: setup"
TICKET_SH="$(dirname "$setup_path")/scripts/ticket.sh"
[[ -f "$TICKET_SH" ]] || runner_failure "tracker script missing: $TICKET_SH"
}
resolve_log_file() {
local requested="$1" parent
if [[ "$requested" != /* ]]; then
requested="$REPO_ROOT/$requested"
fi
parent="$(dirname "$requested")"
mkdir -p -- "$parent" || return 1
parent="$(cd "$parent" && pwd -P)" || return 1
printf '%s/%s' "$parent" "$(basename "$requested")"
}
initialize_run() {
local new_run="true" existing_status="" existing_run_id="" existing_created_at=""
local existing_log_mirror="" existing_activity="" existing_completed_ref="" existing_next_ref="" existing_result_file=""
if [[ -f "$STATE_FILE" ]]; then
validate_state "$STATE_FILE" || runner_failure "runner state is invalid: $STATE_FILE"
read_state_fields "$STATE_FILE" '[
(.status // "interrupted"),
.run_id,
.created_at,
(.log_mirror_file // ""),
(.activity_file // ""),
(.completed_ref // ""),
(.next_ref // ""),
(.result_file // "")
]'
existing_status="${STATE_FIELDS[0]:-interrupted}"
existing_run_id="${STATE_FIELDS[1]:-}"
existing_created_at="${STATE_FIELDS[2]:-}"
existing_log_mirror="${STATE_FIELDS[3]:-}"
existing_activity="${STATE_FIELDS[4]:-}"
existing_completed_ref="${STATE_FIELDS[5]:-}"
existing_next_ref="${STATE_FIELDS[6]:-}"
existing_result_file="${STATE_FIELDS[7]:-}"
[[ "$existing_status" == "complete" ]] || new_run="false"
fi
if [[ "$new_run" == "true" ]]; then
CREATED_AT="$(timestamp)"
local run_hash
run_hash="$(printf '%s\0%s\0%s\0%s' "$REPO_ROOT" "$ROOT_REF" "$CREATED_AT" "$$-$RANDOM" | git hash-object --stdin)"
RUN_ID="autopilot-$run_hash"
else
RUN_ID="$existing_run_id"
CREATED_AT="$existing_created_at"
LAST_COMPLETED_REF="$existing_completed_ref"
NEXT_REF_STATE="$existing_next_ref"
RESULT_FILE_STATE="$existing_result_file"
fi
RUN_DIR="$RUNS_DIR/$RUN_ID"
mkdir -p -- "$RUN_DIR" || runner_failure "could not create run directory: $RUN_DIR"
LOG_FILE="$(run_log_file "$RUN_ID")"
if [[ -n "$LOG_FILE_OVERRIDE" ]]; then
LOG_MIRROR_FILE="$(resolve_log_file "$LOG_FILE_OVERRIDE")" || runner_failure "could not resolve log path: $LOG_FILE_OVERRIDE"
if [[ -n "$existing_log_mirror" && "$LOG_MIRROR_FILE" != "$existing_log_mirror" ]]; then
runner_failure "resumed run already mirrors its log to: $existing_log_mirror"
fi
elif [[ -n "$existing_log_mirror" ]]; then
LOG_MIRROR_FILE="$existing_log_mirror"
fi
if [[ "$new_run" == "false" && -n "$existing_activity" ]]; then
ACTIVITY_FILE="$existing_activity"
else
ACTIVITY_FILE="$RUN_DIR/activity"
fi
touch "$LOG_FILE" "$ACTIVITY_FILE" || runner_failure "could not initialize run log: $LOG_FILE"
[[ -z "$LOG_MIRROR_FILE" ]] || touch "$LOG_MIRROR_FILE" || runner_failure "could not initialize log mirror: $LOG_MIRROR_FILE"
RUN_STATUS="running"
RUN_PHASE="starting"
RUNNER_PID_STATE="$$"
WORKERS_JSON="[]"
FINISHED_AT=""
SUMMARY=""
REASON=""
ITERATION=0
STATE_ACTIVE="true"
persist_state || runner_failure "could not persist runner state: $STATE_FILE"
announce_activity "run $RUN_ID started ($PROVIDER)"
announce "worker session $(worker_tuning_summary)"
announce "log $LOG_FILE"
[[ -z "$LOG_MIRROR_FILE" ]] || announce "log mirror $LOG_MIRROR_FILE"
print_observer_commands announce "$TMUX_SESSION"
}
# The integration checkout, its branch, the run's notes directory (the one
# implement-spec's spec-run-state.sh names), and the main checkout that holds the worktrees.
prepare_integration() {
local resolved origin_default common
resolved="$(cd "$INTEGRATION_DIR" 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null)" ||
runner_failure "integration checkout not found: $INTEGRATION_DIR"
INTEGRATION_DIR="$resolved"
BRANCH="$(git -C "$INTEGRATION_DIR" branch --show-current 2>/dev/null || true)"
[[ -n "$BRANCH" ]] || runner_failure "the integration checkout is on no branch: $INTEGRATION_DIR"
origin_default="$(git -C "$INTEGRATION_DIR" symbolic-ref --short -q refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')" || true
DEFAULT_BRANCH="${origin_default:-main}"
if [[ "$BRANCH" == "$DEFAULT_BRANCH" || ( -z "$origin_default" && "$BRANCH" == "master" ) ]]; then
runner_failure "the integration checkout is on $BRANCH: create the spec's integration branch first (the autopilot skill does it), then pass its checkout as --integration"
fi
common="$(cd "$INTEGRATION_DIR" && cd "$(git rev-parse --git-common-dir)" && pwd -P)" ||
runner_failure "could not resolve the Git common directory"
NOTES_DIR="$common/implement-spec/$BRANCH"
mkdir -p -- "$NOTES_DIR/screenshots" || runner_failure "could not create the notes directory: $NOTES_DIR"
MAIN_CHECKOUT="$(git -C "$INTEGRATION_DIR" worktree list --porcelain | sed -n '1s/^worktree //p')"
[[ -n "$MAIN_CHECKOUT" ]] || MAIN_CHECKOUT="$REPO_ROOT"
BASE_SHA=""
[[ ! -f "$NOTES_DIR/base_sha" ]] || BASE_SHA="$(tr -d '[:space:]' <"$NOTES_DIR/base_sha")"
# No worker of this root is running (the runner lock says so): a landing lock left by an
# interrupted run is stale.
rm -f -- "$NOTES_DIR/land.lock/owner"
rmdir "$NOTES_DIR/land.lock" 2>/dev/null || true
# Board lines an earlier run wrote were relayed then.
[[ ! -f "$NOTES_DIR/board.jsonl" ]] || BOARD_LINES_SEEN="$(wc -l <"$NOTES_DIR/board.jsonl" | tr -d ' ')"
}
# Workers have no ticket-board tool: they append one JSON object per board change to
# $NOTES_DIR/board.jsonl (a stage, one finding, one open entry, one stack PR). Each new line is announced
# as `board <json>`, and the launching session sends it to the board.
relay_board() {
local file="$NOTES_DIR/board.jsonl" total line
[[ -f "$file" ]] || return 0
total="$(wc -l <"$file" | tr -d ' ')"
[[ "$total" -gt "$BOARD_LINES_SEEN" ]] || return 0
while IFS= read -r line; do
[[ -n "$line" ]] || continue
announce_activity "board $line"
done < <(sed -n "$((BOARD_LINES_SEEN + 1)),${total}p" "$file")
BOARD_LINES_SEEN="$total"
}
clear_land_lock() {
local ticket_branch="$1" owner=""
[[ -f "$NOTES_DIR/land.lock/owner" ]] && owner="$(sed -n '1p' "$NOTES_DIR/land.lock/owner")"
[[ "$owner" == "$ticket_branch" ]] || return 0
rm -f -- "$NOTES_DIR/land.lock/owner"
rmdir "$NOTES_DIR/land.lock" 2>/dev/null || true
}
build_prompt() {
local cwd="$1" manifest="$2"
printf '%s\n' \
"You are one fresh top-level worker in an external Autopilot loop." \
"Read and follow this worker contract completely: $WORKER_PATH" \
"Target repository (main checkout): $MAIN_CHECKOUT" \
"Your working directory: $cwd" \
"Autopilot run ID: $RUN_ID" \
"Workflow: $IMPLEMENT_SPEC_PATH" \
"Worker manifest (JSON): $manifest" \
"Do exactly the manifest's unit, in its mode. Your first output must be a tool call that reads the worker contract. Emit the structured result once, as your last action. continue requires a non-empty completed_ref and an empty next_ref."
}
terminal_exit_for_status() {
case "$1" in
complete) printf '0' ;;
needs_input) printf '2' ;;
blocked) printf '3' ;;
failed) printf '4' ;;
*) return 1 ;;
esac
}
validate_result() {
local result_file="$1"
jq -e '
type == "object" and
(.status == "continue" or .status == "complete" or .status == "needs_input" or .status == "blocked" or .status == "failed") and
(.completed_ref | type == "string") and
(.next_ref | type == "string") and
(.summary | type == "string") and
(.reason | type == "string") and
(keys | sort == ["completed_ref", "next_ref", "reason", "status", "summary"])
' "$result_file" >/dev/null 2>&1
}
# ---- worker slots ----------------------------------------------------------------------
# One directory per worker under $TEMP_DIR/w/<label>: <label> is the ticket number, or
# "finish". Bash 3.2 has no associative arrays, so the files are the table.
running_labels() {
local slot
for slot in "$TEMP_DIR"/w/*/; do
[[ -f "${slot}pid" && ! -f "${slot}reaped" ]] || continue
slot="${slot%/}"
printf '%s\n' "${slot##*/}"
done
return 0
}
running_count() {
running_labels | wc -l | tr -d ' '
}
worker_is_running() {
[[ -f "$TEMP_DIR/w/$1/pid" && ! -f "$TEMP_DIR/w/$1/reaped" ]]
}
list_has() {
[[ " $1 " == *" $2 "* ]]
}
# Rebuilds what cleanup() kills and what --status shows from the live slots.
refresh_children() {
local label slot pid entries=""
CHILD_PIDS=()
CHILD_PROCESS_GROUPS=()
while IFS= read -r label; do
[[ -n "$label" ]] || continue
slot="$TEMP_DIR/w/$label"
pid="$(sed -n '1p' "$slot/pid")"
CHILD_PIDS+=("$pid" "$(sed -n '1p' "$slot/event_reader_pid")" "$(sed -n '1p' "$slot/error_reader_pid")")
[[ ! -f "$slot/pgid" ]] || CHILD_PROCESS_GROUPS+=("$(sed -n '1p' "$slot/pgid")")
entries="$entries$(jq -cn \
--arg label "$label" \
--arg mode "$(sed -n '1p' "$slot/mode")" \
--arg pid "$pid" \
--arg process_started "$(sed -n '1p' "$slot/process_started")" \
--arg started_at "$(sed -n '1p' "$slot/started_at")" \
--arg cwd "$(sed -n '1p' "$slot/cwd")" \
'{label:$label,mode:$mode,pid:($pid|tonumber),process_started:$process_started,started_at:$started_at,cwd:$cwd}')
"
done < <(running_labels)
WORKERS_JSON="$(printf '%s' "$entries" | jq -sc '.')"
}
capture_reported_model() {
local label captured changed=1
while IFS= read -r label; do
[[ -n "$label" && -s "$TEMP_DIR/w/$label/model" ]] || continue
captured="$(sed -n '1p' "$TEMP_DIR/w/$label/model")"
if [[ -n "$captured" && "$captured" != "$REPORTED_MODEL" ]]; then
REPORTED_MODEL="$captured"
changed=0
fi
done < <(running_labels)
return "$changed"
}
# launch_worker <label> <mode> <cwd> <prompt> <ref>
launch_worker() {
local label="$1" mode="$2" cwd="$3" prompt="$4" ref="$5"
local slot="$TEMP_DIR/w/$label" attempt_id event_file worker_pid worker_pgid runner_pgid
LAUNCHES=$((LAUNCHES + 1))
ITERATION="$LAUNCHES"
rm -rf -- "$slot"
mkdir -p -- "$slot"
attempt_id="$(date -u '+%Y%m%dT%H%M%SZ')-$$-$LAUNCHES"
event_file="$RUN_DIR/$attempt_id.$label.$PROVIDER.events.jsonl"
touch "$event_file" "$slot/activity"
: >"$slot/model"
printf '%s\n' "$event_file" >"$slot/event_file"
printf '%s\n' "$mode" >"$slot/mode"
printf '%s\n' "$ref" >"$slot/ref"
printf '%s\n' "$cwd" >"$slot/cwd"
mkfifo "$slot/events.pipe" "$slot/errors.pipe"
# The readers and the provider are forked with these set: each keeps its own copy.
WORKER_LABEL="$label"
WORKER_CWD="$cwd"
WORKER_ACTIVITY_FILE="$slot/activity"
MODEL_CAPTURE_FILE="$slot/model"
process_event_stream "$event_file" <"$slot/events.pipe" &
printf '%s\n' "$!" >"$slot/event_reader_pid"
process_error_stream <"$slot/errors.pipe" &
printf '%s\n' "$!" >"$slot/error_reader_pid"
set -m
(
set +e
"$PROVIDER_EXECUTOR" "$prompt" "$slot/result.json" "$slot/events.pipe" "$slot/errors.pipe" </dev/null
worker_exit=$?
printf '%s\n' "$worker_exit" >"$slot/exit"
exit "$worker_exit"
) &
worker_pid=$!
set +m
WORKER_LABEL=""
WORKER_CWD=""
WORKER_ACTIVITY_FILE=""
MODEL_CAPTURE_FILE=""
worker_pgid="$(ps -o pgid= -p "$worker_pid" 2>/dev/null | tr -d '[:space:]')"
runner_pgid="$(ps -o pgid= -p "$$" 2>/dev/null | tr -d '[:space:]')"
if [[ "$worker_pgid" =~ ^[1-9][0-9]*$ && "$worker_pgid" != "$runner_pgid" ]]; then
printf '%s\n' "$worker_pgid" >"$slot/pgid"
fi
now_epoch >"$slot/started"
timestamp >"$slot/started_at"
process_started_at "$worker_pid" >"$slot/process_started"
printf '%s\n' "$worker_pid" >"$slot/pid"
refresh_children
RUN_PHASE="workers"
persist_state || runner_failure "could not update worker state"
announce_activity "worker $label started (session $LAUNCHES/$MAX_ITERATIONS, $mode, $(worker_tuning_summary))"
}
reap_workers() {
local label pid labels=()
while IFS= read -r label; do
[[ -n "$label" ]] && labels+=("$label")
done < <(running_labels)
[[ ${labels[0]+present} ]] || return 0
for label in "${labels[@]}"; do
pid="$(sed -n '1p' "$TEMP_DIR/w/$label/pid")"
if [[ -f "$TEMP_DIR/w/$label/exit" ]] || ! kill -0 "$pid" 2>/dev/null; then
reap_worker "$label"
fi
done
}
reap_worker() {
local label="$1" slot="$TEMP_DIR/w/$1" pid pgid="" reader waited=0 worker_exit=1
pid="$(sed -n '1p' "$slot/pid")"
[[ ! -f "$slot/exit" ]] || worker_exit="$(sed -n '1p' "$slot/exit")"
wait "$pid" 2>/dev/null || true
[[ ! -f "$slot/pgid" ]] || pgid="$(sed -n '1p' "$slot/pgid")"
# The session is over. Whatever it left running (a dev server, a watcher) still holds the
# event pipes open: end it, so the readers finish.
[[ -z "$pgid" ]] || kill -TERM -- "-$pgid" 2>/dev/null || true
for reader in "$(sed -n '1p' "$slot/event_reader_pid")" "$(sed -n '1p' "$slot/error_reader_pid")"; do
while kill -0 "$reader" 2>/dev/null && [[ "$waited" -lt 50 ]]; do
sleep 0.1
waited=$((waited + 1))
done
if kill -0 "$reader" 2>/dev/null; then
[[ -z "$pgid" ]] || kill -KILL -- "-$pgid" 2>/dev/null || true
kill "$reader" 2>/dev/null || true
fi
wait "$reader" 2>/dev/null || true
done
if [[ -s "$slot/model" ]]; then
REPORTED_MODEL="$(sed -n '1p' "$slot/model")"
fi
"$PROVIDER_RESULT_EXTRACTOR" "$(sed -n '1p' "$slot/event_file")" "$slot/result.json" || true
touch "$slot/reaped"
refresh_children
[[ "$(running_count)" -gt 0 ]] || RUN_PHASE="reconciling"
persist_state || runner_failure "could not update worker state"
DISPATCH_NEEDED="true"
handle_worker_result "$label" "$worker_exit"
}
# A unit that failed keeps its claim and its worktree: the next run of the same command
# resumes it. The run stops dispatching, lets the other workers land, and ends failed.
fail_unit() {
local label="$1" reason="$2"
FAILED_LIST="$FAILED_LIST $label"
[[ -n "$FAILURE_REASON" ]] || FAILURE_REASON="$label: $reason"
DRAINING="true"
record_retro_session "$label" failed
announce_activity "worker $label failed: $reason"
}
# A worker session that failed or was blocked is a retro candidate: the finish worker mines
# it and lists environment fixes in its report. The file lives in the run directory, so a
# resumed run (same run ID) still sees the attempts an earlier invocation failed.
RETRO_SESSIONS_LIMIT=5
record_retro_session() {
local label="$1" outcome="$2" slot="$TEMP_DIR/w/$1" event_file
# Only a session that ran and ended (a worktree failure has none), and only once.
[[ -f "$slot/reaped" && ! -f "$slot/retro_recorded" ]] || return 0
event_file="$(sed -n '1p' "$slot/event_file" 2>/dev/null)"
[[ -s "$event_file" ]] || return 0
printf '%s\t%s\t%s\n' "$label" "$outcome" "$event_file" >>"$RUN_DIR/retro-sessions.tsv" || return 0
touch "$slot/retro_recorded"
}
# retro_sessions_json: the most recent candidates, newest last, as a JSON array.
retro_sessions_json() {
[[ -s "$RUN_DIR/retro-sessions.tsv" ]] || { printf '[]\n'; return 0; }
tail -n "$RETRO_SESSIONS_LIMIT" "$RUN_DIR/retro-sessions.tsv" \
| jq -Rcs 'split("\n") | map(select(. != "") | split("\t") | {ticket: .[0], outcome: .[1], events: .[2]})'
}
handle_worker_result() {
local label="$1" worker_exit="$2" slot="$TEMP_DIR/w/$1" mode ref status completed reason summary next
mode="$(sed -n '1p' "$slot/mode")"
ref="$(sed -n '1p' "$slot/ref")"
[[ "$mode" != "build" ]] || clear_land_lock "$BRANCH--$label"
if [[ "$worker_exit" != "0" ]]; then
fail_unit "$label" "the $PROVIDER worker process exited $worker_exit"
return 0
fi
if ! validate_result "$slot/result.json"; then
fail_unit "$label" "the $PROVIDER worker returned an invalid result"
return 0
fi
cp -- "$slot/result.json" "$RUN_DIR/result-$label.json" || true
status="$(jq -r '.status' "$slot/result.json")"
completed="$(jq -r '.completed_ref' "$slot/result.json")"
next="$(jq -r '.next_ref' "$slot/result.json")"
reason="$(jq -r '.reason' "$slot/result.json")"
summary="$(jq -r '.summary' "$slot/result.json")"
announce_activity "worker $label result $status: $summary"
if [[ "$mode" == "finish" ]]; then
FINISH_STATUS="$status"
FINISH_REASON="$reason"
FINISH_NEXT_REF="$next"
return 0
fi
case "$status" in
continue|complete)
if [[ -z "$completed" || "${completed##*/}" != "${ref##*/}" ]]; then
fail_unit "$label" "the worker completed '${completed:-nothing}' instead of $ref"
return 0
fi
if ! ticket_is_landed "$label" || ! git -C "$INTEGRATION_DIR" merge-base --is-ancestor "$BRANCH--$label" "$BRANCH" 2>/dev/null; then
fail_unit "$label" "the worker reported $ref built, but $BRANCH--$label is not landed on $BRANCH"
return 0
fi
LAST_COMPLETED_REF="$ref"
frontier_refresh
announce_activity "ticket $label merged ($(landed_numbers | wc -l | tr -d ' ') of $(frontier_query '[.tickets[] | select(.delivery | not)] | length') landed on $BRANCH)"
announce_assumptions "$label"
if [[ "$(ticket_field "$label" '.deploy_gate')" == "true" ]]; then
announce_activity "ticket $label is a deploy gate: its dependents wait for the deploy"
fi
;;
needs_input)
release_ticket "$ref" "autopilot $RUN_ID: needs an answer before this is built: $reason"
RELEASED_LIST="$RELEASED_LIST $label"
QUESTIONS="$QUESTIONS${QUESTIONS:+; }$label: $reason"
announce_activity "question $label: $reason"
;;
blocked)
release_ticket "$ref" "autopilot $RUN_ID: blocked: $reason"
BLOCKED_LIST="$BLOCKED_LIST $label"
BLOCKERS="$BLOCKERS${BLOCKERS:+; }$label: $reason"
record_retro_session "$label" blocked
announce_activity "ticket $label blocked: $reason"
;;
failed)
fail_unit "$label" "$reason"
;;
esac
}
# A build worker that built on an assumed answer writes one `Assumed:` line per choice in
# its report. Each one is announced, so the launching session can put it to the user.
announce_assumptions() {
local label="$1" line
[[ -f "$NOTES_DIR/$label.md" ]] || return 0
while IFS= read -r line; do
[[ -n "$line" ]] || continue
line="${line#Assumed:}"
announce_activity "ticket $label assumed: ${line# }"
done < <(grep -E '^Assumed:' "$NOTES_DIR/$label.md" || true)
}
# ---- dispatch --------------------------------------------------------------------------
# ensure_worktree <ticket branch> <path>: prints "new" or "existing".
ensure_worktree() {
local ticket_branch="$1" worktree="$2" current
if [[ -d "$worktree" ]]; then
current="$(git -C "$worktree" branch --show-current 2>/dev/null || true)"
[[ "$current" == "$ticket_branch" ]] || return 1
printf 'existing'
return 0
fi
mkdir -p -- "$(dirname "$worktree")" || return 1
if git -C "$MAIN_CHECKOUT" rev-parse --verify -q "refs/heads/$ticket_branch" >/dev/null; then
git -C "$MAIN_CHECKOUT" worktree add "$worktree" "$ticket_branch" >/dev/null 2>&1 || return 1
printf 'existing'
else
git -C "$MAIN_CHECKOUT" worktree add -b "$ticket_branch" "$worktree" "$BRANCH" >/dev/null 2>&1 || return 1
printf 'new'
fi
}
ticket_overlaps_running() {
local number="$1" mine="$TEMP_DIR/files-$1" label
ticket_files "$TRACKER_ROOT/$(ticket_ref "$number")" >"$mine"
[[ -s "$mine" ]] || return 1
while IFS= read -r label; do
[[ -n "$label" && -s "$TEMP_DIR/w/$label/files" ]] || continue
if [[ -n "$(comm -12 "$mine" "$TEMP_DIR/w/$label/files")" ]]; then
return 0
fi
done < <(running_labels)
return 1
}
build_manifest() {
local number="$1" selection="$2" ref="$3" ticket_branch="$4" worktree="$5" blockers
blockers="$(frontier_query -c --arg n "$number" --arg notes "$NOTES_DIR" \
'[.tickets[] | select(.number == $n) | .blocked_by[] | {number: ., report: ($notes + "/" + . + ".md")}]')"
jq -cn \
--arg selection "$selection" \
--arg ticket "$number" \
--arg ticket_ref "$ref" \
--arg ticket_file "$TRACKER_ROOT/$ref" \
--arg spec_file "$TRACKER_ROOT/.scratch/$SPEC_SLUG/spec.md" \
--arg decisions_dir "$TRACKER_ROOT/.scratch/$SPEC_SLUG/decisions" \
--arg slug "$SPEC_SLUG" \
--arg branch "$BRANCH" \
--arg ticket_branch "$ticket_branch" \
--arg worktree "$worktree" \
--arg integration "$INTEGRATION_DIR" \
--arg notes "$NOTES_DIR" \
--arg delivery "$DELIVERY" \
--arg land "$LAND_PATH" \
--arg board_file "$NOTES_DIR/board.jsonl" \
--arg head "$(git -C "$INTEGRATION_DIR" rev-parse HEAD 2>/dev/null || true)" \
--argjson blockers "$blockers" \
'{
mode: "build",
selection: $selection,
ticket: $ticket,
ticket_ref: $ticket_ref,
ticket_file: $ticket_file,
spec_file: $spec_file,
decisions_dir: $decisions_dir,
slug: $slug,
branch: $branch,
ticket_branch: $ticket_branch,
worktree: $worktree,
integration: $integration,
notes: $notes,
report_file: ($notes + "/" + $ticket + ".md"),
screenshots: ($notes + "/screenshots"),
delivery: $delivery,
land: $land,
blockers: $blockers,
board_file: $board_file,
integration_head: $head
}'
}
# start_build_worker <number> <frontier|resume>
start_build_worker() {
local number="$1" selection="$2" ref ticket_branch worktree worktree_state manifest
ref="$(ticket_ref "$number")"
if [[ "$LAUNCHES" -ge "$MAX_ITERATIONS" ]]; then
LIMIT_REACHED="true"
DRAINING="true"
return 0
fi
if [[ "$selection" == "frontier" ]] && ! claim_ticket "$ref"; then
BLOCKED_LIST="$BLOCKED_LIST $number"
BLOCKERS="$BLOCKERS${BLOCKERS:+; }$number: claim refused ($CLAIM_REASON)"
announce_activity "ticket $number not claimed ($CLAIM_REASON)"
return 0
fi
ticket_branch="$BRANCH--$number"
worktree="$MAIN_CHECKOUT/.claude/worktrees/$ticket_branch"
if ! worktree_state="$(ensure_worktree "$ticket_branch" "$worktree")"; then
fail_unit "$number" "could not create the worktree $worktree for $ticket_branch"
return 0
fi
[[ "$worktree_state" == "new" ]] || selection="resume"
manifest="$(build_manifest "$number" "$selection" "$ref" "$ticket_branch" "$worktree")"
announce_activity "selected $ref ($selection, worktree $worktree)"
launch_worker "$number" build "$worktree" "$(build_prompt "$worktree" "$manifest")" "$ref"
ticket_files "$TRACKER_ROOT/$ref" >"$TEMP_DIR/w/$number/files"
}
unit_is_skipped() {
list_has "$RELEASED_LIST" "$1" || list_has "$BLOCKED_LIST" "$1" || list_has "$FAILED_LIST" "$1"
}
dispatch_frontier() {
local number own=() ready=()
frontier_refresh
while IFS= read -r number; do
[[ -n "$number" ]] && own+=("$number")
done < <(frontier_query --arg id "autopilot:$RUN_ID" \
'.tickets[] | select(.claimed_by == $id and .derived != "closed" and (.delivery | not)) | .number')
while IFS= read -r number; do
[[ -n "$number" ]] && ready+=("$number")
done < <(frontier_query '.tickets[] | select(.derived == "ready" and (.delivery | not)) | .number')
# This run's own interrupted claims first, then the ready frontier, lowest number first.
if [[ ${own[0]+present} ]]; then
for number in "${own[@]}"; do
[[ "$DRAINING" == "false" && "$(running_count)" -lt "$CONCURRENCY" ]] || return 0
if unit_is_skipped "$number" || worker_is_running "$number" || ticket_is_landed "$number"; then
continue
fi
start_build_worker "$number" resume
done
fi
if [[ ${ready[0]+present} ]]; then
for number in "${ready[@]}"; do
[[ "$DRAINING" == "false" && "$(running_count)" -lt "$CONCURRENCY" ]] || return 0
if unit_is_skipped "$number" || worker_is_running "$number" || ticket_is_landed "$number"; then
continue
fi
ticket_waits_on_gate "$number" && continue
if ticket_overlaps_running "$number"; then
record_activity "ticket $number waits: its Files overlap a running ticket's"
continue
fi
start_build_worker "$number" frontier
done
fi
}
start_finish_worker() {
local pending="$1" delivery_ticket="$2" manifest
if [[ "$LAUNCHES" -ge "$MAX_ITERATIONS" ]]; then
runner_failure "maximum worker sessions reached ($MAX_ITERATIONS) before the finish worker could start"
fi
FINISH_RAN="true"
FINISH_MERGED="$pending"
RUN_STAGE="finish"
manifest="$(jq -cn \
--arg spec_file "$TRACKER_ROOT/.scratch/$SPEC_SLUG/spec.md" \
--arg tracker_root "$TRACKER_ROOT" \
--arg slug "$SPEC_SLUG" \
--arg branch "$BRANCH" \
--arg default_branch "$DEFAULT_BRANCH" \
--arg integration "$INTEGRATION_DIR" \
--arg notes "$NOTES_DIR" \
--arg base_sha "$BASE_SHA" \
--arg delivery "$DELIVERY" \
--arg cleanup "$CLEANUP" \
--arg board_file "$NOTES_DIR/board.jsonl" \
--arg merged "$pending" \
--arg delivery_ticket "$delivery_ticket" \
--arg gates "$(landed_gate_numbers | paste -sd' ' -)" \
--arg released "$QUESTIONS${QUESTIONS:+${BLOCKERS:+; }}$BLOCKERS" \
--argjson retro_sessions "$(retro_sessions_json)" \
'{
mode: "finish",
spec_file: $spec_file,
tracker_root: $tracker_root,
slug: $slug,
branch: $branch,
default_branch: $default_branch,
integration: $integration,
notes: $notes,
base_sha: (if $base_sha == "" then null else $base_sha end),
delivery: $delivery,
cleanup: $cleanup,
board_file: $board_file,
merged: ($merged | split(" ") | map(select(. != ""))),
delivery_ticket: (if $delivery_ticket == "" then null else $delivery_ticket end),
deploy_gates: ($gates | split(" ") | map(select(. != ""))),
left_open: (if $released == "" then null else $released end),
retro_sessions: $retro_sessions
}')"
announce_activity "every buildable ticket is landed: starting the finish worker (review, verify, resolve, deliver as $DELIVERY)"
launch_worker "finish" finish "$INTEGRATION_DIR" "$(build_prompt "$INTEGRATION_DIR" "$manifest")" ".scratch/$SPEC_SLUG/spec.md"
}
set_terminal() {
TERMINAL_STATUS="$1"
TERMINAL_NEXT_REF="$2"
TERMINAL_REASON="$3"
}
# Nothing is running and nothing was dispatched: finish, or stop.
decide_when_idle() {
local pending delivery_ticket=""
if [[ -n "$FAILED_LIST" ]]; then
set_terminal failed "" "$FAILURE_REASON"
return 0
fi
if [[ "$LIMIT_REACHED" == "true" ]]; then
runner_failure "maximum worker sessions reached ($MAX_ITERATIONS) before the spec was built"
fi
frontier_refresh
if [[ -n "$RELEASED_LIST$BLOCKED_LIST" && "$FINISH_NOW" != "true" ]]; then
if [[ -n "$RELEASED_LIST" ]]; then
set_terminal needs_input "" "answers needed before these tickets are built: $QUESTIONS. Record each answer in the spec's decisions/ on $BRANCH, then run the same command again; add --finish-now to deliver what is landed without them."
else
set_terminal blocked "" "tickets that could not be built: $BLOCKERS. Unblock them and run the same command again; add --finish-now to deliver what is landed without them."
fi
return 0
fi
pending="$(merged_pending_numbers | paste -sd' ' -)"
delivery_ticket="$(frontier_query '[.tickets[] | select(.delivery and .derived == "ready")][0].path // ""')"
if [[ "$FINISH_RAN" != "true" && -n "$pending$delivery_ticket" ]]; then
start_finish_worker "$pending" "$delivery_ticket"
return 0
fi
tracker_idle_outcome
set_terminal "$TRACKER_OUTCOME" "$TRACKER_NEXT_REF" "$TRACKER_REASON"
}
conclude_finish() {
local number
if [[ -n "$FAILED_LIST" ]]; then
set_terminal failed "" "$FAILURE_REASON"
return 0
fi
case "$FINISH_STATUS" in
continue|complete)
frontier_refresh
for number in $FINISH_MERGED; do
if [[ "$(ticket_field "$number" '.derived')" != "closed" ]]; then
set_terminal failed "" "the finish worker reported success, but ticket $number is not closed ($(ticket_field "$number" '.status'))"
return 0
fi
record_activity "ticket $number closed"
done
tracker_idle_outcome
if [[ "$TRACKER_OUTCOME" != "complete" && -n "$QUESTIONS$BLOCKERS" ]]; then
set_terminal needs_input "" "delivered without these tickets: $QUESTIONS${QUESTIONS:+${BLOCKERS:+; }}$BLOCKERS"
else
set_terminal "$TRACKER_OUTCOME" "$TRACKER_NEXT_REF" "${FINISH_REASON:+$FINISH_REASON; }$TRACKER_REASON"
fi
;;
needs_input|blocked|failed)
set_terminal "$FINISH_STATUS" "$FINISH_NEXT_REF" "$FINISH_REASON"
;;
*)
set_terminal failed "" "the finish worker returned no result"
;;
esac
}
emit_terminal() {
local result_file="$TEMP_DIR/terminal.json"
case "$TERMINAL_STATUS" in
complete) SUMMARY="Autopilot scope is complete." ;;
needs_input) SUMMARY="Autopilot reached a human gate." ;;
blocked) SUMMARY="Autopilot has no autonomous frontier." ;;
failed) SUMMARY="Autopilot stopped." ;;
*) runner_failure "cannot terminate with status: $TERMINAL_STATUS" ;;
esac
REASON="$TERMINAL_REASON"
NEXT_REF_STATE="$TERMINAL_NEXT_REF"
jq -cn \
--arg status "$TERMINAL_STATUS" \
--arg completed_ref "$LAST_COMPLETED_REF" \
--arg next_ref "$TERMINAL_NEXT_REF" \
--arg summary "$SUMMARY" \
--arg reason "$REASON" \
'{status:$status,completed_ref:$completed_ref,next_ref:$next_ref,summary:$summary,reason:$reason}' >"$result_file"
RESULT_FILE_STATE="$RUN_DIR/last-result.json"
cp -- "$result_file" "$RESULT_FILE_STATE" || runner_failure "could not persist the terminal result"
TERMINAL_EXIT="$(terminal_exit_for_status "$TERMINAL_STATUS")"
transition_to_terminal "$TERMINAL_STATUS"
persist_state || runner_failure "could not persist terminal state"
announce_activity "$SUMMARY"
[[ -z "$REASON" ]] || announce "$REASON"
[[ -z "$NEXT_REF_STATE" ]] || announce_activity "next $NEXT_REF_STATE"
jq -c . "$result_file"
}
heartbeat() {
local now label slot started last_event age elapsed message
if capture_reported_model; then
persist_state || true
fi
now="$(now_epoch)"
[[ "$now" -ge "$NEXT_HEARTBEAT" ]] || return 0
NEXT_HEARTBEAT=$((now + HEARTBEAT_SECONDS))
while IFS= read -r label; do
[[ -n "$label" ]] || continue
slot="$TEMP_DIR/w/$label"
started="$(sed -n '1p' "$slot/started")"
last_event="$(file_mtime "$slot/activity")"
age=$((now - last_event))
elapsed=$((now - started))
message="worker $label alive (session $LAUNCHES/$MAX_ITERATIONS, model ${REPORTED_MODEL:-$WORKER_MODEL}, effort $WORKER_EFFORT, elapsed $(format_duration "$elapsed"), last event $(format_duration "$age") ago)"
if [[ "$age" -ge "$QUIET_SECONDS" ]]; then
message="$message; quiet threshold reached"
fi
announce "$message"
done < <(running_labels)
}
run_autopilot_loop() {
TEMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/autopilot.XXXXXX")" || runner_failure "could not create a temporary directory"
SCHEMA_JSON="$(jq -c . "$SCHEMA_PATH")"
mkdir -p -- "$TEMP_DIR/w"
LAUNCHES=0
prepare_integration
if ! resolve_spec_scope; then
set_terminal "$TRACKER_OUTCOME" "" "$TRACKER_REASON"
emit_terminal
return "$TERMINAL_EXIT"
fi
if ! resolve_tracker_root; then
set_terminal "$TRACKER_OUTCOME" "" "$TRACKER_REASON"
emit_terminal
return "$TERMINAL_EXIT"
fi
persist_state || runner_failure "could not persist run state"
announce_activity "spec $SPEC_SLUG on $BRANCH ($INTEGRATION_DIR); delivery $DELIVERY; up to $CONCURRENCY workers at once; notes $NOTES_DIR"
NEXT_HEARTBEAT=$(( $(now_epoch) + HEARTBEAT_SECONDS ))
while :; do
reap_workers
relay_board
if [[ "$RUN_STAGE" == "build" ]]; then
if [[ "$DRAINING" == "false" && "$DISPATCH_NEEDED" == "true" ]]; then
DISPATCH_NEEDED="false"
dispatch_frontier
fi
if [[ "$(running_count)" -eq 0 ]]; then
decide_when_idle
fi
elif [[ "$(running_count)" -eq 0 ]]; then
conclude_finish
fi
if [[ -n "$TERMINAL_STATUS" ]]; then
emit_terminal
return "$TERMINAL_EXIT"
fi
heartbeat
sleep "$POLL_SECONDS"
done
}
run_autopilot() {
mkdir -p -- "$STATE_DIR" "$RUNS_DIR" || runner_failure "could not create runner state directory: $STATE_DIR"
acquire_runner_lock
initialize_run
run_autopilot_loop
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |