aether-colony 5.1.0 → 5.2.1

package/.aether/commands/council.yaml

@@ -6,9 +6,208 @@ body: |
   ## Instructions
 
   Parse `{{ARGUMENTS}}`:
+  - If starts with `--deliberate`: set `deliberate_mode = true`, extract proposal text after `--deliberate`
   - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
   - Otherwise: set `visual_mode = true`
 
+  **If `deliberate_mode` is true:** Skip to [Deliberation Mode](#deliberation-mode) and stop after it.
+
+  ---
+
+  ## Deliberation Mode
+
+  When `--deliberate "<proposal>"` is passed, run a structured Advocate/Challenger/Sage deliberation.
+
+  ### Step D1: Check Budget
+
+  Run using the Bash tool with description "Checking deliberation budget...":
+  ```bash
+  bash .aether/aether-utils.sh council-budget-check
+  ```
+
+  Parse result. If `allowed` is `false`:
+  ```
+  📜🐜🏛️🐜📜 COUNCIL — BUDGET EXHAUSTED
+
+  Spawn budget is fully allocated. Complete or close existing deliberations before starting new ones.
+  Run /ant:council to review existing deliberations.
+  ```
+  Stop here.
+
+  ### Step D2: Open Deliberation
+
+  Run using the Bash tool with description "Opening deliberation...":
+  ```bash
+  bash .aether/aether-utils.sh council-deliberate --proposal "<proposal>"
+  ```
+
+  Capture `deliberation_id` from `result.id`.
+
+  Display:
+  ```
+  📜🐜🏛️🐜📜 COUNCIL DELIBERATION OPENED
+
+  Proposal: "<proposal>"
+  ID: {deliberation_id}
+  Budget: {budget} spawns available
+
+  Convening Advocate, Challenger, and Sage...
+  ```
+
+  ### Step D3: Spawn Advocate Scout
+
+  Spawn an Advocate scout to argue **in favor** of the proposal.
+
+  {{#claude}}
+  Use the Task tool to spawn a scout with the following system prompt:
+  ```
+  You are the Advocate on the Ant Colony council.
+  Your role is to argue STRONGLY IN FAVOR of the proposal.
+  Present the strongest possible case for why this proposal should be adopted.
+  Be specific. Focus on concrete benefits and outcomes.
+  Keep your argument under 200 words.
+  Reply with ONLY your argument text — no preamble or meta-commentary.
+  ```
+
+  And user message:
+  ```
+  Proposal: "<proposal>"
+
+  Present your strongest argument in favor of this proposal.
+  ```
+
+  Capture the advocate's argument as `advocate_argument`.
+  {{/claude}}
+
+  Record the argument:
+  ```bash
+  bash .aether/aether-utils.sh council-advocate \
+    --deliberation-id "<deliberation_id>" \
+    --argument "<advocate_argument>"
+  ```
+
+  Display:
+  ```
+  ⚖️  ADVOCATE:
+  {advocate_argument}
+  ```
+
+  ### Step D4: Spawn Challenger Scout
+
+  Spawn a Challenger scout to argue **against** the proposal.
+
+  {{#claude}}
+  Use the Task tool to spawn a scout with the following system prompt:
+  ```
+  You are the Challenger on the Ant Colony council.
+  Your role is to argue STRONGLY AGAINST the proposal.
+  Present the strongest possible case for why this proposal should be rejected or deferred.
+  Be specific. Focus on concrete risks, costs, and downsides.
+  Keep your argument under 200 words.
+  Reply with ONLY your argument text — no preamble or meta-commentary.
+  ```
+
+  And user message:
+  ```
+  Proposal: "<proposal>"
+
+  Present your strongest argument against this proposal.
+  ```
+
+  Capture the challenger's argument as `challenger_argument`.
+  {{/claude}}
+
+  Record the argument:
+  ```bash
+  bash .aether/aether-utils.sh council-challenger \
+    --deliberation-id "<deliberation_id>" \
+    --argument "<challenger_argument>"
+  ```
+
+  Display:
+  ```
+  ⚔️  CHALLENGER:
+  {challenger_argument}
+  ```
+
+  ### Step D5: Spawn Sage Scout
+
+  Spawn a Sage scout to synthesize both positions and provide a recommendation.
+
+  {{#claude}}
+  Use the Task tool to spawn a scout with the following system prompt:
+  ```
+  You are the Sage on the Ant Colony council.
+  You have heard both the Advocate and Challenger arguments.
+  Your role is to synthesize both positions into balanced wisdom and provide a clear recommendation.
+  Your recommendation must be one of: adopt, reject, defer, or adopt-with-conditions.
+  Keep your synthesis under 150 words.
+  Reply with JSON only:
+  {"synthesis": "<your balanced synthesis>", "recommendation": "adopt|reject|defer|adopt-with-conditions"}
+  ```
+
+  And user message:
+  ```
+  Proposal: "<proposal>"
+
+  Advocate argued: "<advocate_argument>"
+
+  Challenger argued: "<challenger_argument>"
+
+  Synthesize both positions and provide your recommendation.
+  ```
+
+  Parse the JSON response. Capture `synthesis` and `recommendation`.
+  {{/claude}}
+
+  Record the sage synthesis:
+  ```bash
+  bash .aether/aether-utils.sh council-sage \
+    --deliberation-id "<deliberation_id>" \
+    --synthesis "<synthesis>" \
+    --recommendation "<recommendation>"
+  ```
+
+  ### Step D6: Display Result
+
+  ```
+  📜🐜🏛️🐜📜 COUNCIL DELIBERATION COMPLETE
+
+  Proposal: "<proposal>"
+
+  ⚖️  Advocate:
+  {advocate_argument}
+
+  ⚔️  Challenger:
+  {challenger_argument}
+
+  🧙 Sage Synthesis:
+  {synthesis}
+
+  Recommendation: {recommendation}
+  ```
+
+  If recommendation is `adopt` or `adopt-with-conditions`:
+  ```
+  ✅ Council recommends proceeding.
+     Run /ant:focus "<proposal summary>" to inject guidance for the colony.
+  ```
+
+  If recommendation is `reject`:
+  ```
+  ❌ Council recommends against this proposal.
+     Run /ant:redirect "<proposal summary>" if you want to make this a hard constraint.
+  ```
+
+  If recommendation is `defer`:
+  ```
+  ⏸️  Council recommends deferring this decision.
+     Return when more context is available.
+  ```
+
+  ---
+
+
   {{#claude}}
   ### Step 0: Initialize Visual Mode (if enabled)
 
@@ -26,6 +225,12 @@ body: |
   ```
   Stop here.
 
+  If `milestone` == `"Crowned Anthill"`:
+  ```
+  This colony has been sealed. Start a new colony with /ant:init "new goal".
+  ```
+  Stop here.
+
   Capture the current state for context:
   - `prior_state` = state field value (READY, EXECUTING, PLANNING, etc.)
   - `current_phase` = current_phase field value

package/.aether/commands/init.yaml

@@ -135,8 +135,14 @@ body: |
 
   Use Read tool to check `.aether/data/COLONY_STATE.json`.
 
-  - If file exists AND has a non-null `goal` field: set `reinit_mode = true`, store `existing_goal`
-  - Otherwise: set `reinit_mode = false`
+  - If file exists AND has a non-null `goal` field:
+    - Check the `milestone` field. If `milestone == "Crowned Anthill"`:
+      - This is a **sealed colony**. Treat as **fresh init**, NOT re-init.
+      - Set `reinit_mode = false`
+      - Display: `Previous colony was sealed. Starting fresh colony.`
+      - The old COLONY_STATE.json will be overwritten in Step 7 (fresh init path).
+    - Otherwise (colony exists but is NOT sealed): set `reinit_mode = true`, store `existing_goal`
+  - If file does not exist or `goal` is null: set `reinit_mode = false`
 
   If re-init mode, read existing charter entries from `.aether/QUEEN.md`:
   ```bash
@@ -276,14 +282,29 @@ body: |
 
   2. Auto-apply approved pheromone suggestions (see pheromone auto-apply below).
 
-  3. Optionally update the goal field in COLONY_STATE.json in-place:
+  3. Update the goal field in COLONY_STATE.json in-place using the state API:
   ```bash
-  jq --arg new_goal "{approved_intent}" '.goal = $new_goal' .aether/data/COLONY_STATE.json > .aether/data/COLONY_STATE.json.tmp && mv .aether/data/COLONY_STATE.json.tmp .aether/data/COLONY_STATE.json
+  bash .aether/aether-utils.sh state-write "$(jq --arg new_goal "{approved_intent}" '.goal = $new_goal' .aether/data/COLONY_STATE.json)"
   ```
 
-  4. Run `bash .aether/aether-utils.sh session-init "$(jq -r '.session_id' .aether/data/COLONY_STATE.json)" "{approved_intent}"`
+  4. **Verify the write** — read back and confirm goal is set:
+  ```bash
+  verify_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json)
+  if [[ "$verify_goal" == "null" || -z "$verify_goal" ]]; then
+    echo "ERROR: Colony state write failed — goal is still null after write. Re-run /ant:init."
+    # Attempt recovery: write goal directly
+    jq --arg g "{approved_intent}" '.goal = $g' .aether/data/COLONY_STATE.json > .aether/data/COLONY_STATE.json.tmp && mv .aether/data/COLONY_STATE.json.tmp .aether/data/COLONY_STATE.json
+    verify_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json)
+    if [[ "$verify_goal" == "null" || -z "$verify_goal" ]]; then
+      echo "FATAL: Recovery write also failed. Colony state may be corrupted."
+      stop
+    fi
+  fi
+  ```
+
+  5. Run `bash .aether/aether-utils.sh session-init "$(jq -r '.session_id' .aether/data/COLONY_STATE.json)" "{approved_intent}"`
 
-  5. Skip to Step 8 (display result). Do NOT write COLONY_STATE.json from template, do NOT write constraints.json, do NOT write pheromones.json.
+  6. Skip to Step 8 (display result). Do NOT write COLONY_STATE.json from template, do NOT write constraints.json, do NOT write pheromones.json.
 
   **If fresh init:**
 
@@ -299,12 +320,24 @@ body: |
      - Remove ALL keys starting with underscore
      - Write the resulting JSON to `.aether/data/COLONY_STATE.json` using the Write tool
 
-  5. Write constraints.json from template:
+  5. **Verify the write** — read back and confirm COLONY_STATE.json is valid and goal is set:
+  ```bash
+  verify_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json 2>/dev/null)
+  verify_valid=$(jq -e . .aether/data/COLONY_STATE.json >/dev/null 2>&1 && echo "valid" || echo "invalid")
+  if [[ "$verify_valid" != "valid" || "$verify_goal" == "null" || -z "$verify_goal" ]]; then
+    echo "ERROR: Colony state write verification failed (valid=$verify_valid, goal=$verify_goal)"
+    echo "The colony file may be corrupted. Remove .aether/data/COLONY_STATE.json and re-run /ant:init."
+    stop
+  fi
+  echo "Colony state verified: goal=\"$verify_goal\""
+  ```
+
+  6. Write constraints.json from template:
      - Resolve template: check `~/.aether/system/templates/constraints.template.json` first, then `.aether/templates/constraints.template.json`
      - If no template found: output "Template missing: constraints.template.json. Run aether update to fix." and stop
      - Read template, follow `_instructions`, remove `_` prefixed keys, write to `.aether/data/constraints.json`
 
-  6. Initialize runtime files from templates (non-blocking):
+  7. Initialize runtime files from templates (non-blocking):
   ```bash
   for template in pheromones midden learning-observations; do
     if [[ "$template" == "midden" ]]; then
@@ -327,15 +360,15 @@ body: |
   done
   ```
 
-  7. Run `bash .aether/aether-utils.sh context-update init "{approved_intent}"`
-  8. Run `bash .aether/aether-utils.sh validate-state colony`
-  9. Register repo (silent on failure):
+  8. Run `bash .aether/aether-utils.sh context-update init "{approved_intent}"`
+  9. Run `bash .aether/aether-utils.sh validate-state colony`
+  10. Register repo (silent on failure):
   ```bash
   domain_tags=$(bash .aether/aether-utils.sh domain-detect 2>/dev/null | jq -r '.result.tags // ""' || echo "")
   bash .aether/aether-utils.sh registry-add "$(pwd)" "$(jq -r '.version // "unknown"' ~/.aether/version.json 2>/dev/null || echo 'unknown')" --goal "{approved_intent}" --active true --tags "$domain_tags" 2>/dev/null || true
   cp ~/.aether/version.json .aether/version.json 2>/dev/null || true
   ```
-  10. Seed QUEEN.md from hive (non-blocking):
+  11. Seed QUEEN.md from hive (non-blocking):
   ```bash
   domain_tags=$(jq -r --arg repo "$(pwd)" \
     '[.repos[] | select(.path == $repo) | .domain_tags // []] | .[0] // [] | join(",")' \
@@ -345,7 +378,7 @@ body: |
   seed_result=$(bash .aether/aether-utils.sh $seed_args 2>/dev/null || echo '{}')
   seeded_count=$(echo "$seed_result" | jq -r '.result.seeded // 0' 2>/dev/null || echo "0")
   ```
-  11. Run `bash .aether/aether-utils.sh session-init "{session_id}" "{approved_intent}"`
+  12. Run `bash .aether/aether-utils.sh session-init "{session_id}" "{approved_intent}"`
 
   **Pheromone auto-apply (referenced by both re-init and fresh init paths above):**
 

package/.aether/commands/insert-phase.yaml

@@ -13,6 +13,10 @@ body: |
   `No colony initialized. Run /ant:init first.`
   Stop.
 
+  If `milestone` == `"Crowned Anthill"`:
+  `This colony has been sealed. Start a new colony with /ant:init "new goal".`
+  Stop.
+
   If `plan.phases` is empty:
   `No project plan. Run /ant:plan first.`
   Stop.

package/.aether/commands/plan.yaml

@@ -20,7 +20,7 @@ body_claude: |
   3. Output: `State auto-upgraded to v3.0`
   4. Continue with command.
 
-  Extract: `goal`, `plan.phases`
+  Extract: `goal`, `milestone`, `plan.phases`
 
   **Validate:** If `goal: null`:
   ```
@@ -28,6 +28,12 @@ body_claude: |
   ```
   Stop here.
 
+  If `milestone` == `"Crowned Anthill"`:
+  ```
+  This colony has been sealed. Start a new colony with /ant:init "new goal".
+  ```
+  Stop here.
+
   ### Step 1.5: Load State and Show Resumption Context
 
   Run using Bash tool: `bash .aether/aether-utils.sh load-state`
@@ -556,6 +562,26 @@ body_claude: |
 
   Write COLONY_STATE.json.
 
+  **Verify the write** — read back and confirm the plan persisted:
+  ```bash
+  verify_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+  verify_timestamp=$(jq -r '.plan.generated_at' .aether/data/COLONY_STATE.json)
+  verify_state=$(jq -r '.state' .aether/data/COLONY_STATE.json)
+  if [[ "$verify_phases" -lt 1 || "$verify_timestamp" == "null" || "$verify_state" != "READY" ]]; then
+    echo "ERROR: Plan write verification failed (phases=$verify_phases, generated_at=$verify_timestamp, state=$verify_state)"
+    echo "Attempting retry write..."
+    # Retry: re-read, update, write via state API
+    bash .aether/aether-utils.sh state-write "$(jq --argjson phases "$(echo '$PLAN_JSON' | jq '.plan.phases')" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '.plan.phases = $phases | .plan.generated_at = $ts | .state = "READY"' .aether/data/COLONY_STATE.json)"
+    verify_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+    if [[ "$verify_phases" -lt 1 ]]; then
+      echo "FATAL: Retry write also failed. Plan was not persisted."
+      echo "Re-run /ant:plan to regenerate."
+      stop
+    fi
+  fi
+  echo "Plan verified: $verify_phases phases, generated_at=$verify_timestamp, state=$verify_state"
+  ```
+
   Log: `bash .aether/aether-utils.sh activity-log "PLAN_COMPLETE" "queen" "Plan finalized with {confidence}% confidence"`
 
   Update watch-status.txt:
@@ -683,7 +709,7 @@ body_opencode: |
   3. Output: `State auto-upgraded to v3.0`
   4. Continue with command.
 
-  Extract: `goal`, `plan.phases`
+  Extract: `goal`, `milestone`, `plan.phases`
 
   **Validate:** If `goal: null`:
   ```
@@ -691,6 +717,12 @@ body_opencode: |
   ```
   Stop here.
 
+  If `milestone` == `"Crowned Anthill"`:
+  ```
+  This colony has been sealed. Start a new colony with /ant:init "new goal".
+  ```
+  Stop here.
+
   ### Step 1.5: Load State and Show Resumption Context
 
   Run using Bash tool: `bash .aether/aether-utils.sh load-state`
@@ -1220,6 +1252,25 @@ body_opencode: |
 
   Write COLONY_STATE.json.
 
+  **Verify the write** — read back and confirm the plan persisted:
+  ```bash
+  verify_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+  verify_timestamp=$(jq -r '.plan.generated_at' .aether/data/COLONY_STATE.json)
+  verify_state=$(jq -r '.state' .aether/data/COLONY_STATE.json)
+  if [[ "$verify_phases" -lt 1 || "$verify_timestamp" == "null" || "$verify_state" != "READY" ]]; then
+    echo "ERROR: Plan write verification failed (phases=$verify_phases, generated_at=$verify_timestamp, state=$verify_state)"
+    echo "Attempting retry write..."
+    bash .aether/aether-utils.sh state-write "$(jq --argjson phases "$(echo '$PLAN_JSON' | jq '.plan.phases')" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '.plan.phases = $phases | .plan.generated_at = $ts | .state = "READY"' .aether/data/COLONY_STATE.json)"
+    verify_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+    if [[ "$verify_phases" -lt 1 ]]; then
+      echo "FATAL: Retry write also failed. Plan was not persisted."
+      echo "Re-run /ant:plan to regenerate."
+      stop
+    fi
+  fi
+  echo "Plan verified: $verify_phases phases, generated_at=$verify_timestamp, state=$verify_state"
+  ```
+
   Log plan completion: `bash .aether/aether-utils.sh activity-log "PLAN_COMPLETE" "queen" "Plan finalized with {confidence}% confidence"`
 
   Update watch-status.txt:

package/.aether/commands/quick.yaml

@@ -0,0 +1,104 @@
+name: "ant:quick"
+description: "Quick scout query — fast answers without build ceremony"
+description_opencode: "🔍🐜⚡🐜🔍 Quick scout query — fast answers without build ceremony"
+body: |
+  You are the **Queen**. Execute `/ant:quick` — a lightweight scout mission.
+
+  The query is: `{{ARGUMENTS}}`
+
+  ## Purpose
+
+  Quick, focused answers to questions about the codebase, patterns, or implementation
+  details. No build ceremony, no state changes, no verification waves.
+
+  ## Instructions
+
+  ### Step 1: Validate Arguments
+
+  If `{{ARGUMENTS}}` is empty:
+  ```
+  Usage: /ant:quick "<question>"
+
+  Examples:
+    /ant:quick "how does the pheromone system work?"
+    /ant:quick "find all uses of acquire_lock"
+    /ant:quick "what tests cover midden-write?"
+    /ant:quick "show me the colony-prime token budget logic"
+  ```
+  Stop here.
+
+  ### Step 2: Generate Scout Name
+
+  {{TOOL_PREFIX "Naming scout..."}}
+  ```bash
+  bash .aether/aether-utils.sh generate-ant-name "scout"
+  ```
+
+  Capture the output as `scout_name`.
+
+  ### Step 3: Spawn Scout
+
+  Display:
+  ```
+  ━━━ Quick Scout ━━━
+  Spawning {scout_name} — {query truncated to 50 chars}
+  ```
+
+  {{TOOL_PREFIX "Dispatching scout..."}}
+  ```bash
+  bash .aether/aether-utils.sh spawn-log "Queen" "scout" "{scout_name}" "Quick query: {query}"
+  ```
+
+  {{#claude}}
+  Spawn a Scout agent (using Task tool with subagent_type="aether-scout") with this prompt:
+
+  ```
+  You are {scout_name}, a Scout Ant on a quick mission.
+
+  Query: {query from ARGUMENTS}
+
+  Work:
+  1. Search the codebase to answer the query
+  2. Use Grep, Glob, and Read tools to find relevant code
+  3. Provide a clear, focused answer
+  4. Include file paths and line numbers for key findings
+
+  Keep your answer concise and actionable. This is a quick mission —
+  don't explore exhaustively, focus on the most relevant answer.
+
+  Return your findings as a clear text answer (not JSON).
+  ```
+  {{/claude}}
+  {{#opencode}}
+  Investigate the query directly using available tools (Grep, Glob, Read).
+  Search the codebase and provide a clear, focused answer with file paths and line numbers for key findings.
+  Keep your answer concise and actionable.
+  {{/opencode}}
+
+  ### Step 4: Display Results
+
+  {{#claude}}
+  Display the Scout's answer directly to the user.
+  {{/claude}}
+  {{#opencode}}
+  Display your findings directly to the user.
+  {{/opencode}}
+
+  {{TOOL_PREFIX "Recording scout completion..."}}
+  ```bash
+  bash .aether/aether-utils.sh spawn-complete "{scout_name}" "completed" "Quick query answered"
+  ```
+
+  ### Step 5: Update Session (lightweight)
+
+  {{TOOL_PREFIX "Updating session..."}}
+  ```bash
+  bash .aether/aether-utils.sh session-update "/ant:quick" "" "Quick query: {query truncated to 60 chars}" 2>/dev/null || true
+  ```
+
+  **NOTE:** This command does NOT:
+  - Modify COLONY_STATE.json
+  - Advance phases
+  - Create checkpoints
+  - Spawn watchers or chaos ants
+  - Run verification

package/.aether/commands/resume-colony.yaml

@@ -25,8 +25,9 @@ body_claude: |
   If successful:
   1. Parse state from result
   2. If goal is null: Show "No colony state found..." message and stop
-  3. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
-  4. Extract all state fields for display
+  3. If `milestone` == `"Crowned Anthill"`: Show "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop
+  4. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
+  5. Extract all state fields for display
 
   Keep state loaded (don't unload yet) - we'll need it for the full display.
 
@@ -214,8 +215,9 @@ body_opencode: |
   If successful:
   1. Parse state from result
   2. If goal is null: Show "No colony state found..." message and stop
-  3. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
-  4. Extract all state fields for display
+  3. If `milestone` == `"Crowned Anthill"`: Show "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop
+  4. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
+  5. Extract all state fields for display
 
   Keep state loaded (don't unload yet) - we'll need it for the full display.
 

package/.aether/commands/resume.yaml

@@ -60,6 +60,7 @@ body: |
 
   COLONY_STATE.json is the authoritative source for goal and state (session.json may be stale). Extract:
   - `goal` (use this as authoritative, overriding session.json colony_goal)
+  - `milestone` (check for sealed colony)
   - `state` (READY, PLANNING, EXECUTING, PAUSED)
   - `current_phase`
   - `plan.phases` (array with id, name, status for each phase)
@@ -67,6 +68,14 @@ body: |
   - `memory.decisions` (flat list — do NOT distinguish user vs Claude origin)
   - `events` (last 5 for recent activity context)
 
+  **If `milestone` == `"Crowned Anthill"`:** This colony has been sealed. Display:
+  ```
+  This colony has been sealed (Crowned Anthill).
+
+  Start a new colony with /ant:init "new goal"
+  ```
+  Stop here — do NOT display stale phase data from the sealed colony.
+
   If the file is missing or the JSON cannot be parsed, **stop immediately** and display:
 
   ```

package/.aether/commands/run.yaml

@@ -28,6 +28,7 @@ body: |
   - `--replan-interval N` — Pause for replan suggestion every N phases (default: 2)
   - `--continue` — Resume after a replan pause without replanning
   - `--dry-run` — Preview plan without executing
+  - `--headless` — Run without interactive prompts; queue decisions for later review
   - `--verbose` / `-v`, `--no-visual`, `--no-suggest` — Pass through to playbooks
 
   ```
@@ -36,6 +37,7 @@ body: |
   /ant:run --replan-interval 3   Suggest replan every 3 phases instead of 2
   /ant:run --continue            Resume after replan pause without replanning
   /ant:run --dry-run             Preview the autopilot plan
+  /ant:run --headless            Run all phases without interactive prompts
   /ant:run --max-phases 3 -v     Run 3 phases with verbose output
   ```
 
@@ -61,10 +63,14 @@ body: |
   ### Step 0: Initialize
 
   1. Read `.aether/data/COLONY_STATE.json`; validate goal + plan.phases exist
+     - If `milestone` == `"Crowned Anthill"`: output "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop
   2. Determine remaining incomplete phases; apply `--max-phases` cap
   3. Set `phases_completed = 0`, `autopilot_start = $(date +%s)`
   4. Record pre-build blocker count: `bash .aether/aether-utils.sh flag-check-blockers {phase}`
-  5. Display: `AUTOPILOT ENGAGED | Goal: {goal} | Phase {N} | Max: {max or "all"}`
+  5. If `--headless` flag is present:
+     - Run: `bash .aether/aether-utils.sh autopilot-set-headless true`
+     - Display: `Headless mode: ON — interactive prompts will be queued as pending decisions`
+  6. Display: `AUTOPILOT ENGAGED | Goal: {goal} | Phase {N} | Max: {max or "all"}`
 
   ### Step 1: Build Phase
 
@@ -95,6 +101,19 @@ body: |
   specific issues, and instruction: "Fix issues, then run /ant:run to resume."
   Log: `"<timestamp>|autopilot_paused|run|Paused at Phase {id}: {reason}"`
 
+  **Headless override for visual checkpoints:** If headless mode is active and a
+  visual checkpoint prompt would normally be shown to the user, instead queue it as
+  a pending decision:
+  ```bash
+  bash .aether/aether-utils.sh pending-decision-add \
+    --title "Visual checkpoint: Phase {id}" \
+    --type "checkpoint" \
+    --description "{checkpoint_description}" \
+    --phase "{id}" \
+    --source "build-pause-check"
+  ```
+  Then continue without pausing.
+
   **If no pause:** proceed to Step 3.
 
   ### Step 3: Continue (Verify + Advance)
@@ -112,6 +131,18 @@ body: |
   Skip the AskUserQuestion prompt. Instead, auto-PAUSE with reason
   "Runtime verification required" so the user can test manually before resuming.
 
+  **Headless override for runtime verification:** If headless mode is active and
+  runtime verification would normally pause, queue as a pending decision instead:
+  ```bash
+  bash .aether/aether-utils.sh pending-decision-add \
+    --title "Runtime verification needed: Phase {id}" \
+    --type "runtime-verification" \
+    --description "Manual testing required before advancing past Phase {id}" \
+    --phase "{id}" \
+    --source "continue-gates"
+  ```
+  Then continue without pausing.
+
   ### Step 4: Continue Pause Check
 
   **PAUSE if ANY of these are true:**
@@ -181,6 +212,11 @@ body: |
   {paused}        -> Fix {reason}, then /ant:run to resume
   ```
 
+  If headless mode was active and pending decisions were queued, display:
+  ```
+  Pending decisions: {N} — run `pending-decision-list` to review
+  ```
+
   Update session:
   `bash .aether/aether-utils.sh session-update "/ant:run" "/ant:run" "Autopilot: {N} phases, now Phase {current}"`