Report submit_output from complete() and drop autoAdvance

The handler reconstructed the cursor before the director mutated on
tool.done, so parallel submit_output could both claim an advance.
complete() now returns already-complete vs not-current and the handler
reports that result. autoAdvance is removed from the plugin contract
because the coordinator no longer reads it.

Author: TheGreatAxios

CHANGELOG.md

@@ -13,6 +13,13 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 
 ## [Unreleased]
 
+### Changed
+
+- Completing a workflow step is a `submit_output` tagged with that step's id.
+  `advance_workflow` is gone. Already-complete and not-current ids are
+  acknowledged without advancing. The unused `autoAdvance` workflow field is
+  removed.
+
 ## [0.3.10] - 2026-08-30
 
 ### Fixed

docs/ARCHITECTURE.md

@@ -173,7 +173,7 @@ Compaction replaces older turns with a structured, workflow-aware summary rather
 
 - `ask_operator` — Pauses for a clarifying question with a list of options (and optional shell pre-approval via `command`).
 - `present` — Renders structured UI from a JSON view spec instead of pasting tables into chat.
-- `submit_output` — Completes a workflow step when `step` is set (observed by the workflow coordinator). The step id is compared atomically against the current step; duplicate or stale ids are acknowledged without advancing. Always advertised so activating a workflow does not grow the tools array.
+- `submit_output` — Completes a workflow step when `step` is set. The step id is compared atomically against the current step (`complete()`); already-complete ids (behind the cursor) and not-current ids (future or unknown) are acknowledged without advancing. Always advertised so activating a workflow does not grow the tools array.
 
 Core agent tools (advertised in every chat turn) include `manage_tasks`, `tool_search`, `use_skill`, **`task`** (spawn a sub-agent), and **`search_agents`** when sub-agent profiles are available — see Sub-agents below.
 
@@ -185,7 +185,7 @@ Workflows are named, ordered recipes the agent follows step by step — a thin l
 - `capabilities.ts` — `detectCapabilities` maps the live tool surface to abstract capabilities (`ticket-tracker`, `code-host`, `doc-search`) by name pattern; `resolveStep` decides whether a step runs. A capability override set forces integrations off per run. Adding a capability is a data edit, not a logic change.
 - `runtime.ts` — `WorkflowRuntime` drives execution on a call stack: it skips capability-unsatisfied steps, descends into sub-workflow references, emits step lifecycle events, and snapshots `WorkflowState`. `state.ts` persists that snapshot atomically to `workflow.json` under the session state root for resume.
 
-- `coordinator.ts` — bridges runtime and director: produces the `[WORKFLOW STEP i/total: label]` directive injected into each turn's system prompt, and compare-and-advances the runtime when a `submit_output` tagged `{ step }` completes. Shared by both directors. Fresh and resumed runs share one listener path.
+- `coordinator.ts` — bridges runtime and director: produces the `[WORKFLOW STEP i/total: label]` directive injected into each turn's system prompt, and compare-and-advances the runtime when a `submit_output` tagged `{ step }` completes. Already-complete and not-current ids are acknowledged without moving the cursor. Shared by both directors. Fresh and resumed runs share one listener path.
 - The built-in recipes: the atomics `update-ticket`, `improve-docs`, `write-tests`, `triage-bug`, `code-review`, `scope-project`, and the `build-feature` composite that chains them.
 
 Invocation: workflows are **not** top-level slash commands. Recipe definitions load into the `WORKFLOWS` registry from **enabled workflow/command plugins** at startup; command surfaces on those plugins (e.g. a workflow plugin's command prefix such as `/mywf scope`). Slash commands may also be authored as data-only markdown (`commands/*.md`, no `index.ts`); see PLUGINS.md. The model never suggests or auto-starts workflows from ordinary chat. Skills (bundled `corbits-skills`, enabled plugins, or `.agents/skills/`) load on demand via `use_skill` or as `/<skill-name>` slash commands when `user-invocable` is not `false` (see Skills below). The TUI surfaces state via `src/tui/workflow-controller.ts` (lifecycle, capability overrides, resume) — the header shows step progress (`⟳ name · step/total label`).

src/agent/director.ts

@@ -256,8 +256,8 @@ export const submitOutputDefinition: ToolDefinition = {
   name: "submit_output",
   description:
     "Call this when the task is fully complete (include summary) or to complete " +
-    "a workflow step (step id is required to advance; duplicate or stale step " +
-    "ids are acknowledged without advancing).",
+    "a workflow step (step id is required to advance; already-complete and " +
+    "not-current step ids are acknowledged without advancing).",
   inputSchema: {
     type: "object",
     properties: {

src/agent/tools.ts

@@ -34,6 +34,7 @@ import { sessionModeEnablesSubAgents } from "../config/session-mode.js";
 import { advertisedToolNamesForSessionMode, type ToolAvailability } from "./tool-search.js";
 import type { ProviderCatalogEntry } from "../config/index.js";
 import type { AgentProfile } from "./profiles.js";
+import type { WorkflowCompleteResult } from "../workflows/types.js";
 import {
   createTaskTool,
   runSubAgent,
@@ -137,12 +138,10 @@ export interface AgentToolsetArgs {
   // every turn (workflow or not), so the model can call it with nothing active;
   // this lets its handler report an honest no-op instead of a false advance.
   isWorkflowActive?: () => boolean;
-  // Current workflow step id, read live so the handler can distinguish a
-  // matching complete from a duplicate, stale, or future id without advancing.
-  getCurrentWorkflowStepId?: () => string | null;
-  // True when `stepId` is behind the cursor in the active workflow frame.
-  // Omitted (tests, exec) treats a non-current id as unknown/future, not stale.
-  isPastWorkflowStep?: (stepId: string) => boolean;
+  // Compare-and-advance the live workflow. The handler reports this result
+  // instead of reconstructing the cursor; omitted (exec, tests) never claims
+  // an advance.
+  completeWorkflowStep?: (stepId: string) => WorkflowCompleteResult;
   // Primary session mode (always orchestrator; kept for call-site wiring).
   sessionMode?: SessionMode;
   // Session-start facts gating lsp advertisement. Omitted callers (tests,
@@ -473,11 +472,11 @@ export async function createAgentToolset(args: AgentToolsetArgs): Promise<AgentT
     }),
     stringTool({
       definition: submitOutputDefinition,
-      // The director observes this call and compare-and-advances the workflow
-      // runtime; the handler only acknowledges so the model gets a clean tool
-      // result. Duplicate, stale, and future step ids succeed without claiming
-      // an advance. Copy distinguishes those cases so a future id is not
-      // reported as already complete.
+      // The director also observes this call on tool.done; complete() is
+      // compare-and-advance so a second pass is a no-op. The handler reports
+      // complete()'s result so parallel submit_output cannot both claim an
+      // advance. Already-complete and not-current ids succeed without
+      // claiming one.
       handler: async (rawArgs: Record<string, unknown>): Promise<string> => {
         const parsed = SubmitOutputArgs(rawArgs);
         const step = parsed instanceof type.errors ? undefined : parsed.step;
@@ -487,12 +486,12 @@ export async function createAgentToolset(args: AgentToolsetArgs): Promise<AgentT
           if (step === undefined || step.length === 0) {
             return "Error: workflow completion requires a step identifier.";
           }
-          const current = args.getCurrentWorkflowStepId?.() ?? null;
-          if (current === step) {
+          const result = args.completeWorkflowStep?.(step) ?? "not-current";
+          if (result === "advanced") {
             const note = summary !== undefined && summary.length > 0 ? ` (${summary})` : "";
             return `Workflow step marked complete${note}. Advancing to the next step.`;
           }
-          if (args.isPastWorkflowStep?.(step) === true) {
+          if (result === "already-complete") {
             return "This workflow step is already complete. No advance.";
           }
           return "This workflow step is not current. No advance.";

src/director.test.ts

@@ -814,8 +814,7 @@ describe("updateToolDefinitions rewrites infer tools", () => {
 describe("submit_output workflow handler", () => {
   const buildToolset = (opts: {
     isWorkflowActive: () => boolean;
-    getCurrentWorkflowStepId?: () => string | null;
-    isPastWorkflowStep?: (stepId: string) => boolean;
+    completeWorkflowStep?: (stepId: string) => "advanced" | "already-complete" | "not-current";
   }) =>
     createAgentToolset({
       cwd: process.cwd(),
@@ -826,11 +825,8 @@ describe("submit_output workflow handler", () => {
       }),
       onOperatorGate: async () => ({ kind: "cancel" }),
       isWorkflowActive: opts.isWorkflowActive,
-      ...(opts.getCurrentWorkflowStepId !== undefined
-        ? { getCurrentWorkflowStepId: opts.getCurrentWorkflowStepId }
-        : {}),
-      ...(opts.isPastWorkflowStep !== undefined
-        ? { isPastWorkflowStep: opts.isPastWorkflowStep }
+      ...(opts.completeWorkflowStep !== undefined
+        ? { completeWorkflowStep: opts.completeWorkflowStep }
         : {}),
     });
 
@@ -858,51 +854,86 @@ describe("submit_output workflow handler", () => {
     const content = await runSubmit(
       await buildToolset({
         isWorkflowActive: () => true,
-        getCurrentWorkflowStepId: () => "a",
+        completeWorkflowStep: () => "advanced",
       }),
       { summary: "done" },
     );
     expect(content).toContain("requires a step identifier");
     expect(content).not.toContain("Advancing");
   });
 
-  test("acknowledges advancement when the step matches the current step", async () => {
+  test("reports complete() when the step advances", async () => {
     const content = await runSubmit(
       await buildToolset({
         isWorkflowActive: () => true,
-        getCurrentWorkflowStepId: () => "a",
+        completeWorkflowStep: (id) => (id === "a" ? "advanced" : "not-current"),
       }),
       { step: "a" },
     );
     expect(content).toContain("Advancing to the next step");
   });
 
-  test("acknowledges duplicate or stale completions without claiming an advance", async () => {
+  test("reports already-complete without claiming an advance", async () => {
     const content = await runSubmit(
       await buildToolset({
         isWorkflowActive: () => true,
-        getCurrentWorkflowStepId: () => "b",
-        isPastWorkflowStep: (id) => id === "a",
+        completeWorkflowStep: () => "already-complete",
       }),
       { step: "a" },
     );
     expect(content).toContain("already complete");
     expect(content).not.toContain("Advancing");
   });
 
-  test("does not report a future step as already complete", async () => {
+  test("does not report a not-current step as already complete", async () => {
     const content = await runSubmit(
       await buildToolset({
         isWorkflowActive: () => true,
-        getCurrentWorkflowStepId: () => "a",
-        isPastWorkflowStep: () => false,
+        completeWorkflowStep: () => "not-current",
       }),
       { step: "b" },
     );
     expect(content).toContain("not current");
     expect(content).not.toContain("already complete");
     expect(content).not.toContain("Advancing");
   });
+
+  test("omitted completeWorkflowStep does not claim an advance", async () => {
+    const content = await runSubmit(await buildToolset({ isWorkflowActive: () => true }), {
+      step: "a",
+    });
+    expect(content).toContain("not current");
+    expect(content).not.toContain("Advancing");
+  });
+
+  test("parallel submit_output only one reports Advancing", async () => {
+    const { WorkflowRuntime } = await import("./workflows/runtime.js");
+    const workflow = {
+      name: "simple",
+      description: "two steps",
+      steps: [
+        { id: "a", label: "A" },
+        { id: "b", label: "B" },
+      ],
+    };
+    const runtime = new WorkflowRuntime(new Map(), () => workflow);
+    runtime.start(workflow);
+    const toolset = await buildToolset({
+      isWorkflowActive: () => true,
+      completeWorkflowStep: (stepId) => runtime.complete(stepId),
+    });
+    const run = (id: string, step: string) =>
+      toolset.dynamicRunner.run(
+        { id, name: "submit_output", arguments: { step } },
+        new AbortController().signal,
+      );
+    const [first, second] = await Promise.all([run("so-1", "a"), run("so-2", "a")]);
+    await toolset.dispose();
+    const contents = [String(first.content), String(second.content)];
+    expect(contents.filter((c) => c.includes("Advancing"))).toHaveLength(1);
+    expect(contents.filter((c) => c.includes("already complete"))).toHaveLength(1);
+    expect(runtime.currentStep()?.id).toBe("b");
+  });
 });
 
 describe("transient nudges", () => {

src/tui/runner.ts

@@ -1252,7 +1252,7 @@ export async function runTUI(initialConfig: Config): Promise<number> {
       toolAvailability,
     );
     // The workflow controller is built below, after the toolset; the holder lets
-    // submit_output's handler read live workflow-active state without a
+    // submit_output's handler complete the live workflow without a
     // construction-order cycle.
     const workflowControllerHolder: { instance?: WorkflowController } = {};
 
@@ -1276,9 +1276,8 @@ export async function runTUI(initialConfig: Config): Promise<number> {
       getContextDir: () => workdir,
 
       isWorkflowActive: () => workflowControllerHolder.instance?.isActive() === true,
-      getCurrentWorkflowStepId: () => workflowControllerHolder.instance?.currentStepId() ?? null,
-      isPastWorkflowStep: (stepId) =>
-        workflowControllerHolder.instance?.isPastStep(stepId) === true,
+      completeWorkflowStep: (stepId) =>
+        workflowControllerHolder.instance?.complete(stepId) ?? "not-current",
       ...(extraToolPlugins.length > 0 ? { extraToolPlugins } : {}),
       onOperatorGate: (question, options) =>
         new Promise<OperatorResult>((resolve) => {

src/tui/workflow-controller.ts

@@ -12,7 +12,12 @@ import {
   saveWorkflowState,
   warnWorkflowPersistenceFailure,
 } from "../workflows/state.js";
-import type { CapabilityName, StepStatus, Workflow } from "../workflows/types.js";
+import type {
+  CapabilityName,
+  StepStatus,
+  Workflow,
+  WorkflowCompleteResult,
+} from "../workflows/types.js";
 import type { WorkflowEvent } from "../workflows/runtime.js";
 
 export interface CapabilityStatus {
@@ -105,12 +110,8 @@ export class WorkflowController {
     return this.runtime?.isActive() === true;
   }
 
-  currentStepId(): string | null {
-    return this.coordinator?.currentStepId() ?? null;
-  }
-
-  isPastStep(stepId: string): boolean {
-    return this.coordinator?.isPastStep(stepId) === true;
+  complete(stepId: string): WorkflowCompleteResult {
+    return this.coordinator?.complete(stepId) ?? "not-current";
   }
 
   list(): { name: string; description: string }[] {

src/workflows/coordinator.ts

@@ -1,5 +1,5 @@
 import type { WorkflowRuntime } from "./runtime.js";
-import type { WorkflowStep } from "./types.js";
+import type { WorkflowCompleteResult, WorkflowStep } from "./types.js";
 
 // Bridges the workflow runtime and a director. A director consults the
 // coordinator for the directive to inject into each turn's system prompt and
@@ -78,16 +78,23 @@ export class WorkflowCoordinator {
   // the runtime, and only via compare-and-advance against the current step.
   // Returns true when the runtime advanced (used by tests; the directors
   // already reset their idle counters on any tool call, so a workflow
-  // advance is never seen as a stall). Duplicate or stale completions are
-  // acknowledged here without moving the cursor.
+  // advance is never seen as a stall). Already-complete and not-current
+  // completions are acknowledged here without moving the cursor.
   handleToolDone(name: string | undefined, args: unknown, isError: boolean): boolean {
     if (isError || !this.runtime.isActive()) return false;
     if (name !== "submit_output") return false;
     const stepId = stepIdOf(args);
     if (stepId === null) return false;
-    if (this.runtime.complete(stepId) !== "advanced") return false;
-    this.persist();
-    return true;
+    return this.complete(stepId) === "advanced";
+  }
+
+  // Compare-and-advance, persist on a real move, and return the complete()
+  // result so callers (submit_output's handler) report it instead of
+  // reconstructing the cursor.
+  complete(stepId: string): WorkflowCompleteResult {
+    const result = this.runtime.complete(stepId);
+    if (result === "advanced") this.persist();
+    return result;
   }
 }
 

src/workflows/definition.ts

@@ -23,7 +23,6 @@ export interface Workflow {
   description: string;
   autoInvoke?: string;
   stepThrough?: boolean;
-  autoAdvance?: boolean;
   steps: WorkflowStep[];
 }
 

src/workflows/runtime.ts

@@ -8,6 +8,7 @@ import {
   type WorkflowFrame,
   type WorkflowState,
   type WorkflowStep,
+  type WorkflowCompleteResult,
 } from "./types.js";
 
 export type WorkflowEvent =
@@ -96,16 +97,22 @@ export class WorkflowRuntime {
   }
 
   // Compare-and-advance against the current step. Matching `stepId` advances
-  // atomically (check and move happen in this call). Any other id — duplicate
-  // of a step already left behind, a future step, or no active step — is
-  // acknowledged without moving the cursor, so a retry cannot skip ahead.
-  complete(stepId: string): "advanced" | "acknowledged" {
+  // atomically (check and move happen in this call). A step already behind the
+  // cursor is already-complete; a future, unknown, or inactive id is
+  // not-current. Neither acknowledged case moves the cursor, so a retry cannot
+  // skip ahead.
+  complete(stepId: string): WorkflowCompleteResult {
     const current = this.currentStep();
     if (current !== null && current.id === stepId) {
       this.advance();
       return "advanced";
     }
-    return "acknowledged";
+    const view = this.view();
+    if (view !== null) {
+      const idx = view.steps.findIndex((s) => s.step.id === stepId);
+      if (idx !== -1 && idx < view.stepIndex) return "already-complete";
+    }
+    return "not-current";
   }
 
   // Mark the current step complete and move to the next runnable step. Pops