ace-assign 0.53.4 → 0.55.0

data/docs/demo/fork-provider.recording.json

@@ -1,29 +1,27 @@
 {
   "backend": "asciinema",
-  "tape_path": "/home/mc/ace-t.u53.0/ace-assign/docs/demo/fork-provider.tape.yml",
-  "cast_path": "/home/mc/ace-t.u53.0/ace-assign/docs/demo/fork-provider.cast",
-  "visual_path": "/home/mc/ace-t.u53.0/ace-assign/docs/demo/fork-provider.gif",
-  "sandbox_path": "/home/mc/ace-t.u53.0/.ace-local/demo/sandbox/8rekyn",
+  "tape_path": "/home/mc/ace-t.n1d/ace-assign/docs/demo/fork-provider.tape.yml",
+  "cast_path": "/home/mc/ace-t.n1d/ace-assign/docs/demo/fork-provider.cast",
+  "visual_path": "/home/mc/ace-t.n1d/ace-assign/docs/demo/fork-provider.gif",
+  "sandbox_path": "/home/mc/ace-t.n1d/.ace-local/demo/sandbox/8rfe9v",
   "verification": {
-    "status": "scenario-defect",
-    "classification": "scenario_defect",
-    "summary": "Recording scenario failed verification",
-    "retryable": true,
-    "report_path": "/home/mc/ace-t.u53.0/.ace-local/demo/fork-provider-error-report.md",
+    "status": "pass",
+    "classification": "pass",
+    "summary": "Verification passed",
+    "retryable": false,
+    "report_path": null,
     "details": {
-      "cast_path": "/home/mc/ace-t.u53.0/ace-assign/docs/demo/fork-provider.cast",
+      "cast_path": "/home/mc/ace-t.n1d/ace-assign/docs/demo/fork-provider.cast",
       "inputs_recorded": 0,
-      "echoed_commands_recorded": 70,
+      "echoed_commands_recorded": 435,
       "script_commands_recorded": 0,
-      "commands_expected": 7,
+      "commands_expected": 3,
       "captured_vars": {
-        "ACE_TMUX_SESSION": "fork-demo PROJECT_ROOT_PATH=\"$PWD\" ace-assign fork-run --assignment \"$(cat ASSIGN_ID)@010\" --launch-mode tmux --provider codex:gpt@yolo --cli-args \"--no-alt-screen\" --timeout 120"
+        "ACE_TMUX_SESSION": "fork-demo PROJECT_ROOT_PATH=\"$PWD\" ace-assign status --assignment \"$(cat ASSIGN_ID)@010\""
       },
       "missing_vars": [],
-      "missing_output": [
-        "{\"Task context\" => nil}"
-      ],
-      "missing_output_sequence": null,
+      "missing_output": [],
+      "missing_output_sequence": [],
       "forbidden_hits": [],
       "assertion_failures": [],
       "assertions_skipped": false

data/docs/demo/fork-provider.tape.yml

@@ -34,13 +34,17 @@ setup:
     PROJECT_ROOT_PATH="$PWD" ace-assign create --yaml fork-demo-job.yaml
     ruby -e 'link = ".ace-local/assign/.latest"; abort "no latest assignment" unless File.symlink?(link); File.write("ASSIGN_ID", File.basename(File.readlink(link)))'
 - run: tmux new-session -d -s fork-demo -n work -c "$PWD" "bash --noprofile --norc -i"
-- run: |
-    bash -lc 'sleep 45; tmux detach-client -s fork-demo || true' >/tmp/ace-demo-fork-provider-detach.log 2>&1 &
 scenes:
 - name: Attach to the operator work window
   commands:
-  - type: tmux attach -t fork-demo
-    sleep: 2s
+  - tmux:
+      action: attach
+      session: fork-demo
+  - tmux:
+      action: wait
+      for: window-active
+      session: fork-demo
+      window: work
   - type: tmux display-message -p '#W'
     sleep: 2s
 - name: Launch the fork into a visible tmux window
@@ -49,6 +53,14 @@ scenes:
     sleep: 2s
   - type: bash -lc 'ACE_TMUX_SESSION=fork-demo PROJECT_ROOT_PATH="$PWD" ace-assign fork-run --assignment "$(cat ASSIGN_ID)@010" --launch-mode tmux --provider codex:gpt@yolo --cli-args "--no-alt-screen" --timeout 120 &'
     sleep: 35s
+  - tmux:
+      action: wait
+      for: window-exists
+      session: fork-demo
+      window: work-fs
+  - tmux:
+      action: detach
+      session: fork-demo
 verify:
   require_output:
   - work

data/docs/usage.md

@@ -4,8 +4,8 @@ title: ace-assign Usage Guide
 purpose: Complete command reference for ace-assign queue orchestration, hierarchy,
   and fork execution.
 ace-docs:
-  last-updated: '2026-04-01'
-  last-checked: '2026-04-01'
+  last-updated: '2026-04-23'
+  last-checked: '2026-04-23'
 ---
 
 # ace-assign Usage Guide
@@ -47,6 +47,7 @@ ace-test-suite --target all
 ```bash
 ace-assign create --yaml job.yaml
 ace-assign status
+ace-assign start
 ace-assign step
 ace-assign finish --message step-010.md
 ace-assign status
@@ -57,6 +58,7 @@ Use scoped targeting when needed:
 
 ```bash
 ace-assign status --assignment abc123@010.01
+ace-assign start --assignment abc123@010.01
 ace-assign finish --message done.md --assignment abc123@010.01
 ```
 
@@ -118,6 +120,7 @@ Text modes:
 - `compact` (default) prints a short summary, hidden-step stats, and up to 5 upcoming step lines
 - `progress` prints a single summary line
 - `full` prints the full tree/table without step instructions
+- JSON emits `active_steps` for all active steps in scope and `next_step` only when no step is active in that scope
 
 HITL stall behavior:
 
@@ -133,7 +136,7 @@ HITL stall behavior:
 
 ### `ace-assign step [STEP]`
 
-Show instructions for the current in-progress step, the next workable step, or an explicit step number.
+Show instructions for the deepest active step in scope, the next workable pending step when nothing is active, or an explicit step number.
 
 Options:
 
@@ -143,7 +146,7 @@ Options:
 
 ### `ace-assign start [STEP]`
 
-Start next workable pending step, or an explicit pending step in the active assignment.
+Mark the next workable pending step active, or mark an explicit pending step active in the targeted assignment or subtree.
 
 Options:
 
@@ -153,11 +156,11 @@ Options:
 
 ### `ace-assign finish [STEP] --message VALUE`
 
-Complete current in-progress step (or explicit step in active assignment) with report content.
+Complete the current active step (or explicit active step in the active assignment) with report content.
 Use positional `STEP` only for the active assignment. When targeting another
 assignment or a scoped subtree, pass `--assignment <id>` or
 `--assignment <id@step>` without a positional `STEP`; the command finishes the
-current in-progress step in that target.
+deepest active step in that target.
 
 `--message` accepts:
 
@@ -222,6 +225,7 @@ Options:
 - `--cli-args <args>`
 - `--timeout <seconds>`
 - `--launch-mode auto|headless|tmux`
+- `--callback`
 - `--quiet, -q`
 - `--debug, -d`
 
@@ -229,7 +233,25 @@ Launch modes:
 
 - `auto` (default): use tmux when the current process is already inside tmux or `ACE_TMUX_SESSION` is set; otherwise use the headless subprocess path
 - `headless`: force the existing provider subprocess path and never create tmux panes
-- `tmux`: require tmux context, create or reuse `<current-window>-fs`, start a real interactive agent in a pane there via `ace-llm --interactive`, and send the scoped `/as-assign-drive <assignment>@<root>` handoff automatically
+- `tmux`: require tmux context, create or reuse `<origin-window>-fs`, start a real interactive agent in a pane there via `ace-llm --interactive`, and send the scoped `/as-assign-drive <assignment>@<root>` handoff automatically. The fork window name uses the shared `ace-tmux` safe-name policy, so punctuation in the base window is replaced with `-`. Fork windows and panes are created detached, so the current tmux focus stays where the user left it.
+- `tmux`: require tmux context, create or reuse `<origin-window>-fs`, start a real interactive agent in a pane there via `ace-llm --interactive`, and send the scoped `/as-assign-drive <assignment>@<root>` handoff automatically
+  - This mode consumes the shared `ace-tmux` runtime/control surface for tmux targeting, pane dispatch, and diagnostics.
+  - The fork window name uses the shared `ace-tmux` safe-name policy, so punctuation in the base window is replaced with `-`.
+  - Fork windows and panes are created detached, so the current tmux focus stays where the user left it.
+  - Assignment step state remains the source of truth for subtree completion or failure; pane capture is diagnostic support only.
+
+Callback mode:
+
+- `--callback`: tmux-only fork mode that captures the pane where `fork-run` was started and passes it into the child fork session as `ACE_ASSIGN_CALLBACK_PANE`
+- In callback mode the child agent is instructed to send one final status sentence back to the origin pane with `ace-tmux send` before stopping
+- Callback mode is intended for interactive parent/child agent tmux flows where the parent stays idle until the child sends the final message back
+
+Launch-mode precedence for fork execution:
+
+1. CLI `--launch-mode`
+2. Step frontmatter `fork.mode`
+3. Config `execution.launch_mode`
+4. Built-in default `auto`
 
 Provider resolution precedence for fork execution:
 
@@ -247,6 +269,7 @@ status: pending
 context: fork
 fork:
   provider: "claude:sonnet@yolo"
+  mode: "tmux"
 ---
 ```
 

data/handbook/guides/fork-context.g.md

@@ -1,10 +1,11 @@
 ---
 doc-type: guide
 title: Fork Context Guide
-purpose: Explain fork context execution model, boundaries, and recovery patterns for ace-assign subtree delegation.
+purpose: Explain fork context execution model, boundaries, and recovery patterns for
+  ace-assign subtree delegation.
 ace-docs:
-  last-updated: 2026-03-18
-  last-checked: 2026-03-21
+  last-updated: '2026-04-23'
+  last-checked: '2026-04-23'
 ---
 
 # Fork Context Guide
@@ -13,13 +14,14 @@ ace-docs:
 
 Fork context enables step files to run in isolated agent contexts using the Task tool. When a step has `context: fork` in its frontmatter, ace-assign outputs instructions for the orchestrating agent to execute the step via a subagent.
 
-You can also set a per-step provider override with `fork.provider`:
+You can also set per-step launch overrides with `fork.provider` and `fork.mode`:
 
 ```yaml
 ---
 context: fork
 fork:
   provider: "claude:sonnet@yolo"
+  mode: "tmux"
 ---
 ```
 
@@ -30,6 +32,13 @@ Provider precedence during `ace-assign fork-run`:
 3. Assign config `execution.provider`
 4. Built-in default
 
+Launch-mode precedence during `ace-assign fork-run`:
+
+1. CLI `--launch-mode`
+2. Step `fork.mode`
+3. Assign config `execution.launch_mode`
+4. Built-in default `auto`
+
 For hierarchical split workflows, use **parent-only** fork markers:
 - Split parent step: `context: fork`
 - Child steps (`onboard-base`, `task-load`, `plan-task`, `work-on-task`, `verify-test`, `release-minor`): no `context: fork`
@@ -127,6 +136,21 @@ The orchestrating agent:
 - Processes subagent reports
 - Handles failures and retries
 
+## Scoped Status Semantics
+
+Fork execution uses two layers of active ownership:
+
+- The fork root stays `active` while the delegated session owns that subtree.
+- Inside that subtree, zero or one deepest started descendant may also be `active`.
+
+Status reporting is scope-aware:
+
+- Unscoped status lists all `active_steps` in queue order and hides pending descendants under an active fork root from global `next_step` selection.
+- Scoped status (`--assignment <id>@<root>`) reports activity only inside that subtree.
+- When nothing is active inside the current scope, status reports `next_step` instead of predicting started work.
+
+This keeps queue eligibility separate from execution state: pending descendants stay pending until scoped execution explicitly starts them.
+
 ## Recovery From Failed Fork Subtrees
 
 When a forked subtree fails, use **adaptive minimal-safe replay**:
@@ -245,4 +269,4 @@ ACE_DEBUG=1 ace-assign status
 
 - [ace-assign README](../../README.md) - Main documentation
 - [Work Queue Model](../workflow-instructions/drive-assignment.wf.md) - Assignment management
-- `ace-assign fork-run --root <step> --assignment <id>` - Prepare subtree-scoped fork session
+- `ace-assign fork-run --root <step> --assignment <id>` - Prepare subtree-scoped fork session

data/handbook/skills/as-assign-drive/SKILL.md

@@ -12,7 +12,7 @@ allowed-tools:
   - AskUserQuestion
   - Skill
 argument-hint: "[assignment[@scope]]"
-last_modified: 2026-04-07
+last_modified: 2026-04-23
 source: ace-assign
 skill:
   kind: workflow
@@ -29,7 +29,7 @@ Hard stop rule:
 - Do not stop while waiting on a forked subtree; keep polling and resume the parent drive loop as soon as the subtree reaches a terminal state.
 - Treat `ace-assign status --assignment <id>@<root>` as the source of truth for fork completion; quiet terminal output is not enough reason to stop or declare a stall.
 - If a prior terminal or drive session ended, re-enter from assignment state and continue from the next runnable work instead of depending on the old terminal handle.
-- Before any final response, re-check pinned assignment status. If any runnable `pending` or `in_progress` work remains, continue driving.
+- Before any final response, re-check pinned assignment status. If any runnable `pending` or `active` work remains, continue driving.
 - If unrelated dirty files are generated side effects outside task scope, clean/reset them instead of auto-committing them.
 - Use progress updates for partial status only.
 - Return a final user-facing completion response only when the assignment is complete or the workflow reaches an explicit blocker/failure stop condition.

data/handbook/workflow-instructions/assign/drive.wf.md

@@ -12,8 +12,8 @@ doc-type: workflow
 title: Drive Assignment Workflow
 purpose: workflow instruction for driving ace-assign assignment execution
 ace-docs:
-  last-updated: 2026-04-12
-  last-checked: 2026-03-21
+  last-updated: '2026-04-23'
+  last-checked: '2026-04-23'
 ---
 
 # Drive Assignment Workflow
@@ -25,7 +25,7 @@ Drive agent execution through an active assignment by continuously checking stat
 ## Prerequisites
 
 - An active assignment exists (created via `ace-assign create` or `/as-assign-create`)
-- Assignment has at least one pending or in_progress step
+- Assignment has at least one pending or active step
 
 ## Assignment Context Propagation
 
@@ -36,11 +36,11 @@ When working with multiple concurrent assignments, the active assignment is reso
 3. `.latest` symlink (auto-updated on any activity)
 4. Scan all assignments (fallback)
 
-If this workflow is invoked with an argument (for example `/as-assign-drive abc123@010.01`), treat that value as the initial assignment target. If no argument is provided, resolve one active assignment and pin it for the entire loop.
+If this workflow is invoked with an argument (for example `/as-assign-drive abc123@010.01`), treat that exact value as the initial assignment target. If no argument is provided, resolve one active assignment and pin it for the entire loop.
 
 ```bash
-# Set once from workflow argument (empty when not provided)
-ASSIGNMENT_TARGET="${1:-}"
+# Set once from workflow argument or internal scoped default (empty when neither is provided)
+ASSIGNMENT_TARGET="${1:-${ACE_ASSIGN_DEFAULT_TARGET:-}}"
 
 # Resolve and pin assignment identity for the full drive loop
 if [ -n "$ASSIGNMENT_TARGET" ]; then
@@ -59,6 +59,8 @@ if [ -z "$ASSIGNMENT_TARGET" ]; then
 fi
 ```
 
+`ACE_ASSIGN_DEFAULT_TARGET` is an internal fallback passed by `fork-run` launches. If it is present, use it exactly. Do not widen it back to the parent assignment, do not drop the `@<root>` scope suffix, and do not re-resolve an unscoped assignment target later in the loop.
+
 ### Explicit Assignment Targeting (Recommended)
 
 Use explicit flags to propagate assignment context across subprocesses and tools:
@@ -81,7 +83,7 @@ ace-assign status --assignment abc123@010.01
 ace-assign finish --message done.md --assignment abc123@010.01
 ```
 
-When an assignment target includes scope (`<id>@<root>`), `ace-assign finish --message` advances only within that subtree and stops when the subtree is complete.
+When an assignment target includes scope (`<id>@<root>`), `ace-assign finish --message` finishes only within that subtree. Pending descendants remain pending until scoped execution explicitly starts them.
 
 Helper command:
 
@@ -115,7 +117,7 @@ Repeat the following cycle until all steps are done or failed:
 
 ### Run-Until-Blocked Contract
 
-Once `ASSIGNMENT_TARGET` is pinned, keep driving the same assignment until exactly one of these stop conditions is true:
+Once `ASSIGNMENT_TARGET` is pinned, keep driving that exact target until exactly one of these stop conditions is true:
 
 1. `ace-assign status --assignment "$ASSIGNMENT_TARGET"` shows all steps complete
 2. A workflow step explicitly requires HITL or other user judgment before execution can continue
@@ -127,6 +129,7 @@ Do **not** stop merely because you have useful progress to report.
 - Intermediate progress belongs in short progress updates, not in a final completion response.
 - `pending` steps with no active step are not a stop condition. They mean the queue must be advanced and the loop must continue.
 - A batch child subtree finishing is not a completion boundary for the parent assignment.
+- If `ASSIGNMENT_TARGET` includes `@<root>`, that scoped subtree is the entire execution boundary.
 - A paused assignment with remaining runnable work is not "done"; treat it as a recoverable scheduler state and resume the loop.
 
 ### Final Response Gate
@@ -139,20 +142,21 @@ ace-assign status --assignment "$ASSIGNMENT_TARGET" --format json
 
 You may only stop and send a final response when one of these is true:
 
-- the pinned assignment has no remaining runnable `pending` or `in_progress` work
+- the pinned assignment has no remaining runnable `pending` or `active` work
 - the workflow recorded an explicit blocker or unrecoverable failure stop condition
 - the user explicitly interrupted or canceled execution
 
 Do **not** send a final response merely because:
 
-- one child subtree completed
+- one child subtree completed in the parent assignment
 - useful progress was made
 - a prior terminal session ended
-- the parent assignment auto-advanced to the next active step
+- the parent assignment surfaced the next pending step after active work finished
 
 Concrete example:
 
-- `010.01 done` and `010.02.01 in_progress` means continue driving the assignment. It is not a completion boundary.
+- `010.01 done` and `010.02.01 active` means continue driving the assignment. It is not a completion boundary.
+- `040.01 done`, `040.02 done`, and `040.03 done` under `/as-assign-drive <id>@040` means stop the scoped worker. Do not inspect parent step `070` from that scoped process.
 
 ### Step Execution Policy
 
@@ -216,7 +220,7 @@ echo "$STATUS_OUTPUT"
 Read the output to identify:
 
 - Assignment ID (must remain equal to pinned `ASSIGNMENT_ID`)
-- Current step number, name, and status
+- Active step list in scope, or next step when nothing is active
 - Remaining visible steps in the queue preview
 - Hidden-step counts for large queues
 
@@ -264,7 +268,7 @@ Dirty-tree classification rule:
 
 Example:
 
-- A bulk untracked `.ace/...` tree created by `ace-config init` is generated side-effect output. Clean it; do not create a "pre-fork" commit for it.
+- A bulk untracked `.ace/...` tree created by `ace-config sync` is generated side-effect output. Clean it; do not create a "pre-fork" commit for it.
 
 #### Delegation Rule
 
@@ -293,8 +297,15 @@ ace-assign fork-run --assignment <id>@020
 **Delegation boundary rule**
 
 - Outside a delegated fork scope, do NOT execute fork steps inline.
+- First decide whether the fork boundary is already entered before issuing `fork-run`.
 - If scoped status for `--assignment <id>@<root>` already resolves work inside `<root>`, the fork boundary is already entered: continue inline and never call `fork-run` again for the same `<root>`.
-- If the current step is a top-level step with `FORK: yes` and no matching scope is active, delegate immediately.
+- A same-root call to `ace-assign fork-run --assignment <id>@<root>` from inside that exact scoped subtree is invalid and must be treated as an error, not a retry path.
+- If the scoped root itself is active and no child in that subtree is active yet, run:
+
+  - `ace-assign start --assignment "$ASSIGNMENT_TARGET"`
+
+- After a child step inside the scoped subtree becomes active, continue executing that child inline within the same scope.
+- Only if the current step is a top-level step with `FORK: yes` and no matching scope is already active should the driver delegate via `fork-run`.
 
 #### Nested Batch Containers (Container → Fork Children)
 
@@ -374,11 +385,29 @@ Conversational boundary rule:
 ```bash
 STATUS_JSON=$(ace-assign status --assignment "$ASSIGNMENT_TARGET" --format json)
 ASSIGNMENT_ID=$(echo "$STATUS_JSON" | ruby -rjson -e 'puts JSON.parse(STDIN.read).dig("assignment", "id")')
+SCOPED_ROOT="${ASSIGNMENT_TARGET#*@}"
+ACTIVE_STEP=$(echo "$STATUS_JSON" | ruby -rjson -e '
+  scoped_root = ARGV[0].to_s
+  active = Array(JSON.parse(STDIN.read)["active_steps"])
+  child = active.find { |step| step["number"] != scoped_root && step["number"].start_with?("#{scoped_root}.") }
+  puts(child ? child["number"] : active.first&.fetch("number", nil))
+' "$SCOPED_ROOT")
+
+if [ -n "$SCOPED_ROOT" ] && [ "$ACTIVE_STEP" = "$SCOPED_ROOT" ]; then
+  ace-assign start --assignment "$ASSIGNMENT_TARGET"
+  continue
+fi
+
 FORK_ROOT=$(echo "$STATUS_JSON" | ruby -rjson -e '
-  p = JSON.parse(STDIN.read)["current_step"]
-  puts p["number"] if p && p["context"] == "fork"
-')
-if [ -n "$FORK_ROOT" ]; then
+  scoped_root = ARGV[0].to_s
+  active = Array(JSON.parse(STDIN.read)["active_steps"])
+  next_fork = active.find do |step|
+    step["context"] == "fork" &&
+      (scoped_root.empty? || (step["number"] != scoped_root && !step["number"].start_with?("#{scoped_root}.")))
+  end
+  puts next_fork["number"] if next_fork
+' "$SCOPED_ROOT")
+if [ -n "$FORK_ROOT" ] && [ "$FORK_ROOT" != "$SCOPED_ROOT" ]; then
   ace-assign fork-run --assignment "${ASSIGNMENT_ID}@${FORK_ROOT}"
   # Re-check status after subtree delegation completes
   continue
@@ -391,6 +420,14 @@ fi
 
 After launching `ace-assign fork-run`, the driver remains inside the same drive session.
 
+- If fork session metadata includes `callback_pane`, callback mode is active. In that case:
+
+  - do not poll the forked subtree on a timer
+  - do not run the `sleep 360` loop
+  - remain idle after launch and wait for the child forked agent to send a final status message back into the origin pane
+  - treat the callback message as the trigger to resume the parent drive loop
+  - if the callback never arrives and the session is resumed later, recover from assignment state and scoped status instead of waiting forever
+
 - Treat "fork subtree is still running" as an internal progress state, not as a stop condition.
 - Do not end the turn, emit a final user-facing completion summary, or hand control back to the user merely because the driver is waiting on fork completion.
 - Poll the forked subtree every 6 minutes by default. Use two signals on each poll:
@@ -409,6 +446,26 @@ After launching `ace-assign fork-run`, the driver remains inside the same drive
 - A quiet terminal is not a stall by itself. Only treat the fork as stalled when there is no scoped status movement, no new subtree reports, and no process exit for about 30 minutes.
 - When the wait ends, immediately re-enter the parent drive loop. Do not stop between "fork finished" and "next runnable step started."
 
+#### Fork Callback Rule
+
+When `ACE_ASSIGN_CALLBACK_PANE` is present in the forked child environment:
+
+- before stopping for either success or failure, send one final sentence back to the origin pane with direct `ace-tmux send`
+- use the exact pane target from `ACE_ASSIGN_CALLBACK_PANE`
+- use a success sentence shaped like:
+
+  ```bash
+  ace-tmux send --pane "$ACE_ASSIGN_CALLBACK_PANE" --msg "Fork subtree ${FORK_ROOT} for assignment ${ASSIGNMENT_ID} completed. Resume parent assignment drive now." --key Enter
+  ```
+
+- use a failure sentence shaped like:
+
+  ```bash
+  ace-tmux send --pane "$ACE_ASSIGN_CALLBACK_PANE" --msg "Fork subtree ${FORK_ROOT} for assignment ${ASSIGNMENT_ID} failed. Resume parent assignment drive and inspect scoped status." --key Enter
+  ```
+
+- do not invent a new skill or wrapper for this callback; use `ace-tmux send` directly
+
 #### Post-Fork Resume Checklist
 
 Immediately after the fork wait ends, run this checklist in order:
@@ -423,9 +480,20 @@ Immediately after the fork wait ends, run this checklist in order:
    ace-assign start --assignment "$ASSIGNMENT_TARGET"
    ```
 
-6. If pending or `in_progress` work remains and no blocker was recorded, continue the main loop immediately.
+6. If pending or `active` work remains and no blocker was recorded, continue the main loop immediately.
 7. Only stop if the assignment now satisfies a real stop condition from [Run-Until-Blocked Contract](#run-until-blocked-contract).
 
+#### Scoped Worker Completion Boundary
+
+When `ASSIGNMENT_TARGET` already includes `@<root>`, the current process is the subtree worker, not the parent orchestrator.
+
+- After report review, re-check `ace-assign status --assignment "$ASSIGNMENT_TARGET"`.
+- If that scoped status is terminal, stop immediately.
+- Do not query the parent assignment from that scoped worker.
+- Do not widen a scoped target back to parent assignment status.
+- Do not continue into later sibling roots such as `070` from `/as-assign-drive <id>@040`.
+- Parent resume after subtree completion belongs only to the unscoped driver that launched the fork.
+
 Detached-resume rule:
 
 - If a prior drive session or terminal ended, a new `/as-assign-drive` invocation MUST recover from assignment state, not from the old terminal handle.
@@ -509,7 +577,7 @@ After fork-run returns and completion is verified, the driver acts as the **guar
 
 After all fork subtrees within a batch container complete, the container auto-marks as Done. However, the queue pointer may not automatically advance to the next top-level step.
 
-**After verifying all fork subtree reports**, if `ace-assign status` shows no Active step (all completed steps but no new in-progress step), run:
+**After verifying all fork subtree reports**, if `ace-assign status` shows no active step (all completed steps but no new active step), run:
 
 ```bash
 ace-assign start --assignment "$ASSIGNMENT_TARGET"
@@ -717,7 +785,7 @@ Creates a new step linked to the original. Original remains visible as failed.
 ace-assign add "fix-issue" --instructions "Fix the failing tests and verify" --assignment "$ASSIGNMENT_TARGET"
 ```
 
-New step is inserted after the current in-progress step.
+New step is inserted after the current active step.
 
 When the failure evidence is E2E-specific (`ace-test-e2e`, scenario IDs, or `.ace-local/test-e2e/` artifacts), prefer:
 
@@ -748,8 +816,8 @@ echo "$FINAL_STATUS"
 
 Required checks:
 
-- If any steps remain `pending` or `in_progress` and no explicit blocker was recorded, resume the loop instead of stopping.
-- If the assignment is `paused`, `current_step` is `null`, and pending steps remain, run:
+- If any steps remain `pending` or `active` and no explicit blocker was recorded, resume the loop instead of stopping.
+- If the assignment is `paused`, `active_steps` is empty, and `next_step` is present, run:
 
   ```bash
   ace-assign start --assignment "$ASSIGNMENT_TARGET"
@@ -832,7 +900,7 @@ When executing a step with a `skill:` field:
 | Status | Meaning | Next Action |
 |--------|---------|-------------|
 | `pending` | Step not started | Cannot execute (wait for queue) |
-| `in_progress` | Step is active | Execute this step |
+| `active` | Step is active | Execute this step |
 | `done` | Step completed | Move to next step |
 | `failed` | Step failed | Decide: retry, add fix, or abort |
 
@@ -846,11 +914,11 @@ When executing a step with a `skill:` field:
 │   ├── assignment.yaml           # Assignment metadata
 │   ├── steps/                   # Step files (.st.md extension)
 │   │   ├── 010-init.st.md       # done
-│   │   ├── 020-implement.st.md  # in_progress
+│   │   ├── 020-implement.st.md  # active
 │   │   └── 030-test.st.md       # pending
 │   └── reports/                  # Report files (.r.md extension)
 │       ├── 010-init.r.md        # completed report
-│       └── 020-implement.r.md   # in-progress report
+│       └── 020-implement.r.md   # active-step report
 └── def456/
     ├── assignment.yaml
     ├── steps/
@@ -897,28 +965,33 @@ $ ASSIGNMENT_TARGET=8or5kx
 
 # 1. Check status
 $ ace-assign status --assignment "$ASSIGNMENT_TARGET"
-Step 010: onboard [in_progress]
+Next: 010 onboard
+
+# 2. Start the next pending step
+$ ace-assign start --assignment "$ASSIGNMENT_TARGET"
+[Step 010 becomes active]
 
-# 2. Execute step (has skill: onboard)
+# 3. Execute step (has skill: onboard)
 $ /as-onboard
 [Onboarding workflow runs...]
 
-# 3. Write report
+# 4. Write report
 $ ace-assign finish --message onboard-complete.md --assignment "$ASSIGNMENT_TARGET"
-Step 010 marked done, advancing to 020
+[Step 010 marked done]
 
-# 4. Check status again
+# 5. Check status again
 $ ace-assign status --assignment "$ASSIGNMENT_TARGET"
-Step 020: work-on-task [in_progress]
+Next: 020 work-on-task
 
-# 5. Execute next step (has skill: as-task-work)
+# 6. Start and execute next step (has skill: as-task-work)
+$ ace-assign start --assignment "$ASSIGNMENT_TARGET"
 $ /as-task-work 148
 [Task workflow runs...]
 
-# 6. Report and continue...
+# 7. Report and continue...
 $ ace-assign finish --message task-done.md --assignment "$ASSIGNMENT_TARGET"
 
-# 7. Eventually...
+# 8. Eventually...
 $ ace-assign status --assignment "$ASSIGNMENT_TARGET"
 All steps complete!
 ```

data/handbook/workflow-instructions/assign/prepare.wf.md

@@ -141,6 +141,11 @@ For `--taskrefs 148,149,150`, expansion generates:
 030 finalize
 ```
 
+Generated batch parents should carry scheduler metadata:
+
+- `010 batch-tasks (parent, auto-completes, batch_parent: true, parallel: false)`
+- `fork_retry_limit: 1`
+
 The hierarchical numbering enables:
 - Parent auto-completion when all children are done
 - Parent-only fork markers for subtree delegation

data/lib/ace/assign/atoms/preset_expander.rb

@@ -192,6 +192,10 @@ module Ace
 
           step["skill"] = config["skill"] if config["skill"]
           step["context"] = config["context"] if config["context"]
+          step["batch_parent"] = config["batch_parent"] unless config["batch_parent"].nil?
+          step["parallel"] = config["parallel"] unless config["parallel"].nil?
+          step["max_parallel"] = config["max_parallel"] if config["max_parallel"]
+          step["fork_retry_limit"] = config["fork_retry_limit"] unless config["fork_retry_limit"].nil?
 
           step
         end

data/lib/ace/assign/atoms/tree_formatter.rb

@@ -14,14 +14,14 @@ module Ace
       #   #     +-- onboard (completed)
       #   #     +-- work-on-task (running)
       #   #     |   +-- onboard (completed)
-      #   #     |   +-- implement (in_progress)
+      #   #     |   +-- implement (active)
       #   #     |   \-- verify-tests (pending)
       #   #     \-- review-pr (pending)
       module TreeFormatter
         # State display labels matching list command
         STATE_LABELS = {
           pending: "pending",
-          in_progress: "in_progress",
+          active: "active",
           running: "running",
           paused: "paused",
           completed: "completed",