dispatch: add --advance mode to dispatch build for reuse-advance messages (#464)

Advancing a reused worker was the last dispatch-shaped message the FO
still hand-assembled: copying the next stage's full README subsection
verbatim into a SendMessage. `--advance` shares build's machinery
(flag/file plumbing, validation, split-root guidance, fetch-command
emission, dispatch-file write) and swaps in an advance header,
continue-on-entity line, next-stage completion-signal wording, and a
spawn-field-free envelope, cutting the per-advance payload from
O(stage-section) to a fixed ~O(pointer) size.

Updates fo-dispatch-core.md, claude-fo-dispatch.md,
ensign-shared-core.md, and codex-first-officer-runtime.md so the
reuse-advance path routes through the helper, with the old
hand-assembled template demoted to a break-glass fallback.

Co-authored-by: Spike Test <spike@example.com>

Author: clkao

internal/contractlint/reuse_advance_pointer_test.go

@@ -0,0 +1,99 @@
+// ABOUTME: AC-3 structural guard — the reuse-advance path routes through
+// ABOUTME: `dispatch build --advance`, not a hand-assembled verbatim-section message.
+package contractlint
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+var (
+	foDispatchCoreRel   = filepath.Join("skills", "first-officer", "references", "fo-dispatch-core.md")
+	claudeFODispatchRel = filepath.Join("skills", "first-officer", "references", "claude-fo-dispatch.md")
+	ensignSharedCoreRel = filepath.Join("skills", "ensign", "references", "ensign-shared-core.md")
+)
+
+// TestFODispatchCoreReuseNamesAdvanceHelper is AC-3's first anchor:
+// fo-dispatch-core.md's "If reuse" step routes through `«dispatch.build»`
+// `--advance` mode, and the retired claim that the reuse path bypasses the
+// helper entirely is gone (structural absence — a stale claim left in place
+// would contradict the routing this task ships).
+func TestFODispatchCoreReuseNamesAdvanceHelper(t *testing.T) {
+	text := readRepoFile(t, foDispatchCoreRel)
+
+	section := markdownSectionFromText(t, text, "## Reuse and Fresh Dispatch")
+	if !strings.Contains(section, "--advance") {
+		t.Errorf("%s `## Reuse and Fresh Dispatch` does not name --advance — the reuse path must route through `dispatch build --advance`", foDispatchCoreRel)
+	}
+	if !strings.Contains(section, "«dispatch.build»") {
+		t.Errorf("%s `## Reuse and Fresh Dispatch` does not name «dispatch.build» in its \"If reuse\" step", foDispatchCoreRel)
+	}
+
+	retired := "does NOT route through `«dispatch.build»` — assemble the advancement message directly"
+	if strings.Contains(text, retired) {
+		t.Errorf("%s still carries the retired claim %q — the reuse path routes through the helper now", foDispatchCoreRel, retired)
+	}
+	retiredClosingLine := "the reuse-advance path assembles its message directly"
+	if strings.Contains(text, retiredClosingLine) {
+		t.Errorf("%s still carries the retired closing-line claim %q", foDispatchCoreRel, retiredClosingLine)
+	}
+}
+
+// TestClaudeFODispatchReuseAdvanceRoutesThroughHelper is AC-3's second anchor:
+// claude-fo-dispatch.md's reuse-advance handle is `SendMessage(to={handle},
+// message=output.prompt)` — the helper's emitted pointer, forwarded verbatim —
+// with the old hand-assembled verbatim-stage-section template demoted to a
+// break-glass fallback (retained, not deleted, but no longer the live path).
+func TestClaudeFODispatchReuseAdvanceRoutesThroughHelper(t *testing.T) {
+	text := readRepoFile(t, claudeFODispatchRel)
+
+	if !strings.Contains(text, `SendMessage(to="{live worker handle from session roster}", message=output.prompt)`) {
+		t.Errorf("%s missing the reuse-advance handle's live call shape: SendMessage(to={handle}, message=output.prompt)", claudeFODispatchRel)
+	}
+
+	breakGlassHeading := "**Break-glass reuse-advance"
+	breakGlassIdx := strings.Index(text, breakGlassHeading)
+	if breakGlassIdx < 0 {
+		t.Fatalf("%s missing the %q break-glass heading for the reuse-advance fallback", claudeFODispatchRel, breakGlassHeading)
+	}
+
+	verbatimTemplateMarker := "[STAGE_DEFINITION — copy the full ### stage subsection from the README verbatim]"
+	verbatimIdx := strings.Index(text, verbatimTemplateMarker)
+	if verbatimIdx < 0 {
+		t.Errorf("%s no longer carries the verbatim-section template at all — it must be RETAINED as the break-glass fallback, not deleted", claudeFODispatchRel)
+	}
+	if verbatimIdx >= 0 && verbatimIdx < breakGlassIdx {
+		t.Errorf("%s carries the verbatim-section template BEFORE the break-glass heading — it must live under break-glass, not the live reuse-advance path", claudeFODispatchRel)
+	}
+
+	// The reuse-advance handle paragraph (before break-glass) must be the one
+	// naming the live call shape, not the verbatim template.
+	liveSection := text[:breakGlassIdx]
+	if !strings.Contains(liveSection, "message=output.prompt") {
+		t.Errorf("%s live reuse-advance handle section (before break-glass) does not route through output.prompt", claudeFODispatchRel)
+	}
+	if strings.Contains(liveSection, verbatimTemplateMarker) {
+		t.Errorf("%s live reuse-advance handle section (before break-glass) still inlines the verbatim-section template", claudeFODispatchRel)
+	}
+}
+
+// TestEnsignSharedCoreCarriesAdvanceBootstrapClause is AC-3's third anchor:
+// ensign-shared-core.md's DISPATCH_FILE Bootstrap section gains the mid-session
+// advance clause (Read the pointed file on an "Advancing to next stage:"
+// message) with the same DISPATCH_FILE_MISSING failure shape as the initial
+// bootstrap.
+func TestEnsignSharedCoreCarriesAdvanceBootstrapClause(t *testing.T) {
+	text := readRepoFile(t, ensignSharedCoreRel)
+
+	section := markdownSectionFromText(t, text, "## DISPATCH_FILE Bootstrap")
+	if !strings.Contains(section, "Advancing to next stage:") {
+		t.Errorf("%s `## DISPATCH_FILE Bootstrap` does not name the mid-session advance pointer shape (\"Advancing to next stage:\")", ensignSharedCoreRel)
+	}
+	if !strings.Contains(section, "next-stage assignment") {
+		t.Errorf("%s `## DISPATCH_FILE Bootstrap` does not name the next-stage assignment the advance pointer resolves to", ensignSharedCoreRel)
+	}
+	if strings.Count(section, "DISPATCH_FILE_MISSING") < 2 {
+		t.Errorf("%s `## DISPATCH_FILE Bootstrap` must carry the DISPATCH_FILE_MISSING failure shape for BOTH the initial and advance bootstrap paths", ensignSharedCoreRel)
+	}
+}

internal/dispatch/build.go

@@ -83,6 +83,21 @@ type buildOutput struct {
 	RunInBackground *bool    `json:"run_in_background,omitempty"`
 }
 
+// buildAdvanceOutput is the stdout JSON envelope for `--advance` mode: a pointer
+// message for the reuse-advance handle, not a spawn envelope. It carries no
+// subagent_type/name/team_name/run_in_background — nothing is spawned, so those
+// spawn-only fields are absent from the type entirely (not merely omitempty).
+// model stays so the FO's reuse-condition-4 comparator can read
+// next_stage.effective_model from this output instead of a separate README read.
+type buildAdvanceOutput struct {
+	SchemaVersion int      `json:"schema_version"`
+	Description   string   `json:"description"`
+	FetchCommands []string `json:"fetch_commands"`
+	DispatchFile  string   `json:"dispatch_file_path"`
+	Prompt        string   `json:"prompt"`
+	Model         *string  `json:"model"`
+}
+
 // buildError prints `error: {msg}` to stderr and returns code (1 by default).
 func buildError(stderr io.Writer, code int, format string, a ...any) int {
 	fmt.Fprintf(stderr, "error: "+format+"\n", a...)
@@ -168,6 +183,7 @@ func fieldsFromBuildFlags(opts buildOptions, stderr io.Writer) (map[string]json.
 		"stage":          rawJSON(opts.Stage),
 		"checklist":      rawJSON(checklist),
 		"bare_mode":      rawJSON(opts.BareMode),
+		"advance":        rawJSON(opts.Advance),
 	}
 	if opts.TeamName != "" {
 		fields["team_name"] = rawJSON(opts.TeamName)
@@ -281,6 +297,13 @@ func runBuildFields(probe claudeteam.TeamStateProbe, opts buildOptions, fields m
 	}
 	bareMode := optBool(fields, "bare_mode")
 	isFeedbackReflow := optBool(fields, "is_feedback_reflow")
+	advance := optBool(fields, "advance")
+
+	// Rule 13: --advance excludes bare mode. A reuse advance presupposes an
+	// addressable live worker to message; bare mode dispatches nothing addressable.
+	if advance && bareMode {
+		return buildError(stderr, 2, "--advance is incompatible with bare_mode (a reuse advance presupposes an addressable worker; bare mode has none)")
+	}
 
 	// Merged mode is the Claude .178+ team shape: a non-bare claude dispatch with
 	// no team_name. On .178+ TeamCreate/TeamDelete are gone, so team membership is
@@ -526,11 +549,16 @@ func runBuildFields(probe claudeteam.TeamStateProbe, opts buildOptions, fields m
 	// --- Prompt assembly ---
 	var parts []string
 
-	// 0. Operating-contract first-action directive.
-	parts = append(parts, firstActionBlock(host))
-
-	// 1. Header.
-	parts = append(parts, fmt.Sprintf("You are working on: %s\n\nStage: %s\n", entityTitle, stage))
+	// 0-1. Operating-contract first-action directive + header. Advance mode
+	// skips both: the reused worker already holds its operating contract from
+	// initial dispatch, so the file opens with an advance header instead.
+	if advance {
+		parts = append(parts, fmt.Sprintf(
+			"## Advancing to next stage: %s\n\nYou are continuing work on: %s\n", stage, entityTitle))
+	} else {
+		parts = append(parts, firstActionBlock(host))
+		parts = append(parts, fmt.Sprintf("You are working on: %s\n\nStage: %s\n", entityTitle, stage))
+	}
 
 	// 2. Stage definition — replaced by the show-stage-def fetch line. The native
 	// fetch line targets `spacedock dispatch show-stage-def` so the dispatch path
@@ -573,14 +601,27 @@ func runBuildFields(probe claudeteam.TeamStateProbe, opts buildOptions, fields m
 
 	// 4. Entity-read instruction. Under split root the entity lives in the state
 	// checkout; a non-split worktree stage rewrites the path into the worktree.
+	// Advance mode replaces the "Read ... for the spec" wording with a
+	// continue-on-entity instruction — the worker already knows the entity, it is
+	// resuming work on it — using the identical path resolution as fresh dispatch.
 	if worktreePath != "" && !splitRoot {
 		entityRel := pyRelpath(entityPath, gitRoot)
 		worktreeEntityPath = status.PyJoin(worktreePath, entityRel)
-		parts = append(parts, fmt.Sprintf(
-			"Read the entity file at %s for the full spec. It contains:\n", worktreeEntityPath))
+		if advance {
+			parts = append(parts, fmt.Sprintf(
+				"Continue working on the entity at %s.\n", worktreeEntityPath))
+		} else {
+			parts = append(parts, fmt.Sprintf(
+				"Read the entity file at %s for the full spec. It contains:\n", worktreeEntityPath))
+		}
 	} else {
-		parts = append(parts, fmt.Sprintf(
-			"Read the entity file at %s for the current spec.\n", entityPath))
+		if advance {
+			parts = append(parts, fmt.Sprintf(
+				"Continue working on the entity at %s.\n", entityPath))
+		} else {
+			parts = append(parts, fmt.Sprintf(
+				"Read the entity file at %s for the current spec.\n", entityPath))
+		}
 	}
 
 	// 6. Feedback context (conditional).
@@ -672,6 +713,12 @@ func runBuildFields(probe claudeteam.TeamStateProbe, opts buildOptions, fields m
 			dispatchFileName = sessionToken + "-" + derivedName
 		}
 	}
+	if advance {
+		// -advance suffix so an advance file can never alias a fresh-dispatch file
+		// for the same slug+stage: a fresh dispatch after a failed advance would
+		// otherwise collide with the stale advance body at the bare derivedName path.
+		dispatchFileName += "-advance"
+	}
 	if len(dispatchFileName) > dispatchFileNameMaxLen {
 		return buildError(stderr, 1,
 			"dispatch filename '%s' exceeds %d characters", dispatchFileName, dispatchFileNameMaxLen)
@@ -686,7 +733,39 @@ func runBuildFields(probe claudeteam.TeamStateProbe, opts buildOptions, fields m
 		return 1
 	}
 
-	prompt := dispatchPointerPrompt(host, dispatchFilePath)
+	var prompt string
+	if advance {
+		prompt = dispatchAdvancePointerPrompt(stage, dispatchFilePath)
+	} else {
+		prompt = dispatchPointerPrompt(host, dispatchFilePath)
+	}
+
+	// Foot-gun guard: a non-bare claude dispatch that passes team_name selects the
+	// legacy TeamCreate-registry envelope just assembled above (team_name present,
+	// run_in_background absent) rather than the auto-team default — the teamName != ""
+	// complement of mergedMode, the same three signals, no new detection and no
+	// probe. The advisory fires here, after every error guard, so it warns only when
+	// the legacy envelope is actually being emitted; a build that errors out (no
+	// envelope) stays advisory-free. Stderr-only: the envelope above is untouched.
+	// The text lives in the Claude seam beside BareModeAdvisory.
+	if !bareMode && host == "claude" && teamName != "" {
+		claudeteam.LegacyTeamNameAdvisory(stderr)
+	}
+
+	if advance {
+		// Nothing is spawned, so the envelope carries no subagent_type/name/
+		// team_name/run_in_background — only the pointer message and the fields
+		// the FO's reuse-condition-4 comparator still needs (model).
+		outAdvance := buildAdvanceOutput{
+			SchemaVersion: schemaVersion,
+			Description:   fmt.Sprintf("%s: %s", entityTitle, stage),
+			FetchCommands: fetchCommands,
+			DispatchFile:  dispatchFilePath,
+			Prompt:        prompt,
+			Model:         effectiveModel,
+		}
+		return emitBuildJSON(stdout, outAdvance)
+	}
 
 	out := buildOutput{
 		SchemaVersion: schemaVersion,
@@ -711,18 +790,6 @@ func runBuildFields(probe claudeteam.TeamStateProbe, opts buildOptions, fields m
 		out.RunInBackground = &runInBackground
 	}
 
-	// Foot-gun guard: a non-bare claude dispatch that passes team_name selects the
-	// legacy TeamCreate-registry envelope just assembled above (team_name present,
-	// run_in_background absent) rather than the auto-team default — the teamName != ""
-	// complement of mergedMode, the same three signals, no new detection and no
-	// probe. The advisory fires here, after every error guard, so it warns only when
-	// the legacy envelope is actually being emitted; a build that errors out (no
-	// envelope) stays advisory-free. Stderr-only: the envelope above is untouched.
-	// The text lives in the Claude seam beside BareModeAdvisory.
-	if !bareMode && host == "claude" && teamName != "" {
-		claudeteam.LegacyTeamNameAdvisory(stderr)
-	}
-
 	return emitBuildJSON(stdout, out)
 }
 
@@ -887,6 +954,18 @@ func dispatchPointerPrompt(host, dispatchFilePath string) string {
 		dispatchFilePath)
 }
 
+// dispatchAdvancePointerPrompt is the reuse-advance pointer message sent to a
+// live worker in place of the hand-assembled verbatim-stage-section template.
+// Unlike dispatchPointerPrompt, the wording is host-uniform: a reused worker
+// already holds its operating contract from initial dispatch (Claude's
+// Skill(...) invocation included), so no host branches on a skill-wrapper
+// clause here.
+func dispatchAdvancePointerPrompt(stage, dispatchFilePath string) string {
+	return fmt.Sprintf(
+		"Advancing to next stage: %s.\n\nRead %s and treat its content as your next-stage assignment.",
+		stage, dispatchFilePath)
+}
+
 // stateHasOrigin reports whether the state checkout has a named `origin` remote,
 // the named-remote question the split-root sync contract pushes/pulls against —
 // true iff `git remote get-url origin` exits 0. Network-free (unlike ls-remote)
@@ -951,7 +1030,8 @@ func stateCommitGuidance(stateCheckout, entityPath, stateBranch string, hasOrigi
 // emitBuildJSON writes out as two-space-indented JSON with a trailing newline,
 // matching Python json.dumps(indent=2) followed by print() byte-for-byte,
 // including its ensure_ascii escaping of any non-ASCII entity title / prompt.
-func emitBuildJSON(stdout io.Writer, out buildOutput) int {
+// out is buildOutput for a spawn envelope or buildAdvanceOutput for --advance.
+func emitBuildJSON(stdout io.Writer, out any) int {
 	return claudeteam.EmitPythonJSON(stdout, out)
 }
 
@@ -994,6 +1074,9 @@ func emitBuildSchema(stdout io.Writer) int {
 			"is_feedback_reflow": map[string]any{
 				"type": "boolean",
 			},
+			"advance": map[string]any{
+				"type": "boolean",
+			},
 			"host": map[string]any{
 				"type": "string",
 				"enum": []string{"claude", "codex", "pi"},