codingAgent

Starts a local Codex app-server thread for a registered repository. By default it begins in plan mode, then continues into implementation after approval. Set planMode to false to skip planning and start implementation immediately. Flowman stores streamed planning output, multiple-choice questions, reviewer-requested revisions, the approved plan when present, implementation output, and follow-up chat turns. Pending questions and plan reviews appear on the project Approvals page with other human actions. Flowman also derives a concise coding-session name from the prompt, then refines it from the returned plan heading when available, so sessions are easier to scan on the Coding Kanban.

Required configuration

Create a runtime environment under Project settings → Coding agent, then register repository locations for that environment under Coding. Both repositoryId and repositoryName are optional — if neither is supplied, the selected runtime spins Codex up in an ephemeral per-session directory under the OS temp folder. Registered repository names are saved in slug form (lowercase letters, numbers, and dashes) whenever a repository is created or edited. Repository names resolve against enabled repositories in the current project by name or path basename, with case-insensitive and slug-style matching, so workflow inputs such as Flowman Web still match flowman-web. Repository execution uses the selected environment's local path, not the repository's legacy default path. The runtime must be running with CODING_AGENT_RUNTIME_TOKEN , FLOWMAN_ENVIRONMENT, and Convex URL environment variables. The coding-agent runtime runs on Node.js 20.6+ (required for Cursor SDK HTTP/2); use pnpm runtime:coding or the runtime supervisor to start it locally. Repository commands and previews do not inherit the Flowman runtime's application credentials or deployment selectors. They receive a safe OS and tooling baseline plus the project environment snapshot captured when the run starts. Local Codex skills and standard tool login stores remain available through the retained home, path, Codex home, and SSH agent settings. Skills or scripts that require environment-only credentials must receive them through project environment variables. CODEX_BIN can override the Codex executable; otherwise the runtime uses codex. CODEX_MODEL can override the default model used when workflow input does not include a model. Choose the coding backend with workflow input agentProvider (codex or cursor). Cursor sessions require CURSOR_API_KEY on the runtime host and use the local @cursor/sdk agent against the registered repository path. Optional CURSOR_DEFAULT_MODEL overrides the Cursor model when workflow input does not include a model. Cursor local and Cursor Cloud share one catalog: Composer 2.5 remains the default, Composer 2.5 / Cursor Grok 4.6 / Cursor Grok 4.5 / Auto stay available, and the expanded Claude, GPT, Gemini, Kimi, and GLM IDs listed in the Coding Agent workflow Cursor model matrix are selectable. Selected IDs are submitted unchanged. Supported Cursor models expose Reasoning effort (including Max where Cursor provides it) and Flowman maps that value to Cursor effort or reasoning params; Composer and Auto have no effort control. Service-tier / Speed controls remain unavailable for Cursor.

Polyrepo work uses the same repository registration model. Register each sibling repository in the Flowman project and configure its local path for every runtime environment that should edit it. During implementation and follow-up turns, Codex receives write access to all enabled repositories registered for the selected runtime environment, with the selected repository first. Branch preparation, dirty-worktree gating, and changed-file summaries remain scoped to the selected repository. Mark one registered repository as a polyrepo workspace root and assign sibling repositories as workspace members when Commit to PRshould publish coordinated changes. That follow-up turn commits, pushes, creates, and persists one pull request for each changed repository in the configured workspace group; dirty repositories outside the group are ignored. Use a repository's context instructions to describe polyrepo layout, sibling branching rules, and commit or pull request expectations; Flowman snapshots the selected repository's instructions onto each coding session and includes them in planning, implementation, and follow-up prompts.

Optional file and photo attachments use Convex File Storage. The start modal uploads each file directly to Convex, stores only the returned storage id and display metadata in Flowman, then sends attachment ids in the workflow input. File bytes are not stored in run input, prompts, or coding-session documents.

Project admins can also create derived Coding Agent workflows from the Workflows page. A derived workflow stores default values and decides which Coding Agent fields remain visible when starting a run. Existing derived workflows can be edited from the workflow card's pencil action without changing their slug. It posts to the shared /api/workflows/coding-agent route, but Flowman records the run under the derived workflow's own slug after validating that the workflow belongs to the project and uses that route.

Repository records can also define preview targets with a command, port, enabled flag, and auto-start flag. After implementation completes, Flowman queues auto-start targets as preview sessions attached to the coding run; reviewers can also use Preview Changes to start or regenerate a target manually before creating a PR. The runtime reuses an already-running local server when the configured port is reachable, starts only zrok in that case, and keeps the zrok share alive until the coding session is marked done.

In production-style deployments, run one coding-agent runtime process for each Flowman runtime environment/VPS pair. Do not point multiple coding-agent processes at the same FLOWMAN_ENVIRONMENT unless Flowman adds an explicit runtime claim/lease path; queued work is scoped to the selected environment, but the current worker opens a Codex thread before it marks the session as started. Use pnpm runtime:coding when you want to run only the coding-agent runtime.

For local all-in-one development, pnpm runtime:supervisor still runs both runtimes and restarts them after process exits or stale local heartbeats.

Input

runtimeEnvironmentId is required for local runs and must reference an enabled runtime environment in the project; it determines which coding-agent runtime may poll and execute the plan, implementation turns, and follow-up turns. It is not required (and is ignored) for cloud runs — see Execution location below. The repositoryId and repositoryName fields are both optional. If both are supplied, repositoryId wins. If neither is supplied, Codex runs in an ephemeral per-session directory (no repository context, git-aware features such as worktree change tracking are skipped). The planMode field is optional and defaults to true. When false, Flowman creates only the implementation step, starts a Codex thread in default mode, and uses the original prompt as the implementation request.

Hidden designMode turns a plan-mode child workflow into a PRD/design workflow. It requires planMode to stay true. Clarifying questions still pause the run, but the ready artifact is reviewed in a Review Design modal and finalized as a PRD instead of approved for implementation.

The attachments field is optional. When present, it contains Flowman attachment ids created by the upload control. The default Coding agent template allows up to five attachments, with images, PDFs, and text files accepted. Local runtimes download all accepted attachment types before sending the prompt to the coding agent. Both cloud providers receive images as public Convex file URLs. PDF and text attachments remain stored and visible in Flowman but are not sent to cloud executors.

Coding Agent child workflows may define a hidden promptTemplate parameter with a default such as Debug the following issue:{prompt}. At run start, Flowman replaces {prompt} with the submitted user prompt before the orchestrator and stored run input see it. When the template is empty or {prompt}, the user prompt is passed through unchanged.

Child workflows may also save hidden designMode as true for PRD workflows such as Feature Design. Flowman keeps the PRD in the plan field for compatibility, but all review UI labels it as design/PRD and finalization completes the run without creating implementation.

Trigger-dispatched runs preserve the selected child workflow slug when they call the shared Coding Agent route, so child workflow defaults such as promptTemplate are applied before the run is stored and before the orchestrator starts.

{
  "repositoryId": "optional registered coding repository id",
  "repositoryName": "optional repository name when id is omitted",
  "agentProvider": "codex | cursor",
  "location": "local | cloud",
  "prompt": "Describe the coding change.",
  "attachments": [{ "id": "workflowAttachments_..." }],
  "planMode": true,
  "designMode": false,
  "branchMode": "isolated",
  "baseBranch": "optional base branch override",
  "model": "optional model override"
}

Execution location (cloud)

The location field applies to both providers and defaults to local. Local sessions behave exactly as before — a self-hosted runtime polls and executes them against a local checkout. When set to cloud, Convex drives the selected provider's hosted executor and streams results back, so no runtime environment is involved — runtimeEnvironmentId and branchMode are ignored for cloud runs. Cursor uses an isolated Cursor VM. Codex uses background OpenAI Responses, durable conversation state, resumable event streams, and Hosted Shell containers. The starting ref is the resolved baseBranch (per-run override → repository default → main). In a polyrepo run, the per-run override applies only to the selected repository; every other workspace repository uses its own configured default branch and falls back to main when none is stored.

Cloud runs require every included repository to have a GitHub URL configured (Project settings → Coding agent → repository → GitHub URL). A missing legacy default branch safely falls back to main. When the selected repository belongs to a configured polyrepo workspace, Cursor Cloud receives every enabled workspace repository (root and members) — selecting either the workspace root or any member resolves the same complete set. Each repository is supplied exactly once with its own GitHub URL and configured default base branch as startingRef. Standalone repositories (not in a polyrepo workspace) keep single-repository cloud behavior. Flowman validates the full resolved set before creating or recreating a Cursor Cloud agent and fails with one actionable error that names every invalid repository. Disabled workspace members are excluded; inconsistent polyrepo relationships fail validation rather than running against a partial set. The same resolved set is used for plan starts, direct implementation, retries, and agent recreation. Cursor authenticates to GitHub using the connection on the Cursor account behind CURSOR_API_KEY. Follow-up prompts resume the (possibly dormant) cloud agent transparently — the Cursor SDK wakes the environment and replays conversation state when the agent still exists. If Cursor has expired or deleted that agent after a successful turn (including cases where resume succeeds but send fails with agent_not_found), Flowman recreates a fresh cloud agent against the same validated workspace repository set and retries the follow-up once, re-sending the original request and approved plan with that follow-up. Full conversation history from the previous agent is not replayed. Two Cursor provider errors — resource_exhausted and agent_not_found — are different from other implementation failures: they hide the follow-up composer and expose Retry only when the implementation turn itself has failed (Retry resubmits the initial prompt on a fresh cloud agent). If implementation already completed and a later follow-up hits agent_not_found, the follow-up composer stays available and Flowman recreates on send. Any other implementation failure keeps follow-up chat as usual. Codex cloud instead requires a project OPENAI_API_KEY and a connected Flowman GitHub App with repository contents and pull-request write access. It defaults to GPT-5.6 Sol with High reasoning and also offers GPT-5.6 Terra and Luna. OpenAI cloud supports None through Max for GPT-5.6, while local Codex supports Low through Max. GPT-5.5 keeps Low through Extra high. Existinggpt-5.6 selections remain valid as a hidden Sol alias, and Flowman does not expose Pro mode. GPT-5.3-Codex remains local-only and is rejected for Hosted Shell without silently changing models. Plan mode, plan approval/revision, and follow-up chat all work the same as local; only the executor, image attachment transport, and PR creation differ.

Flowman passes the short-lived GitHub App installation credential as separate domain-scoped Hosted Shell secrets: a complete Git Basic authorization header for github.com and a Bearer token forapi.github.com. The agent sees only placeholders, uses the Git credential through command-local options, and never stores either credential in the repository or Git configuration.

Codex cloud checks repositories out under /tmp/flowman/repo. Package-manager dependencies, build caches, and verification output therefore stay outside /mnt/data, which Hosted Shell reserves for downloadable artifacts and limits to 1,000 files. Flowman does not collect downloadable Hosted Shell artifacts in this version.

For Codex cloud, the run drawer treats Responses API assistant text as the authoritative answer. While that text has not arrived, it can show the latest Hosted Shell command output as live progress. Once assistant text is available, it replaces the command-output fallback. Explicit read-only requests complete the workflow with normal run timing and no commit or pull request; write requests with only an empty commit fail without creating an empty PR.

When the workflow run starts, Flowman snapshots project Environment variables into record.env. The selected Coding Agent Integration owns delivery. Local Codex applies the snapshot through its app-server thread environment policy; local Cursor applies the snapshot to the coding-agent runtime process for the duration of each Cursor call so local tools and skills can read those keys. Cursor cloud injects eligible values into its VM. Keys starting with CURSOR_ are excluded (host/platform keys only). Cursor enforces a limit of 50 variables and 4096 bytes per value. Codex cloud uploads the complete run snapshot into its private Hosted Shell container and sources it for agent commands. OPENAI_API_KEY still powers the Responses API, while OPENAI_CLOUD_ALLOWED_DOMAINS configures optional outbound domains. GitHub, registry.npmjs.org, api.convex.dev, and version.convex.dev are always requested. An OpenAI organization admin must enable container networking and approve those defaults plus every optional domain. Hosted Shell has no unrestricted or wildcard network mode. Images are forwarded by public URL, while non-image attachments stay stored in Flowman. Keys named CONVEX_DEPLOYMENT or ending in _CONVEX_DEPLOYMENT automatically contribute their <deployment>.convex.cloud hostname, so those deployment domains do not need to be repeated in OPENAI_CLOUD_ALLOWED_DOMAINS.

Branch management

Working-branch creation applies only to implementation on a registered repository, and ephemeral sessions skip git entirely. Planning does not create branches, but it does refresh the base first — see Base refresh before planning below. The branchMode field defaults to isolated. In isolated mode the runtime cuts a generated feature/<slug> working branch (derived from the plan/session title, falling back to feature/run-<runSlug>) from the configured base before Codex runs. Retries reuse only the working branch recorded for that session. If another run already owns the generated title-based name, Flowman adds the current run slug and creates a separate branch instead of adopting the existing branch. Before cutting a new isolated branch the runtime fetches origin/<base> with an explicit refspec so the remote-tracking tip is refreshed even when the clone's fetch config is narrowed, then cuts from that tip. When an origin remote exists the runtime never falls back to a possibly stale local base. Being checked out on an old feature branch does not change the cut point — isolation always starts from the configured base, not HEAD. If the configured base cannot be resolved the turn fails rather than branching from whatever is checked out. In current mode it builds on whatever branch is checked out, creating nothing; a detached HEAD fails the turn since there is no branch to record. Current mode is enforced for both implementation and follow-up turns: Flowman locks the first recorded working branch, re-checks it out if the agent drifted, injects a mandatory stay-on-branch policy into the prompt, and fails the turn if the checkout still ends on a different branch (for example after a commit/push that created a feature branch).

The base branch resolves as baseBranch (per-run override) → repository.defaultBaseBranch → main. Register a repository's default base branch under Coding. The runtime persists the resulting lineage on the session, shown in the run summary panel and used for PR automation: sourceBranch is the branch you started from (audit only), baseBranch is the PR target, and workingBranch is where the agent committed — a PR is workingBranch → baseBranch. In isolated mode all three can differ: starting a run from feature/auth with default base main records sourceBranch=feature/auth, baseBranch=main, and a generated workingBranch. Current mode keeps sourceBranch and workingBranch on the checked-out branch while preserving the configured baseBranch as the PR target.

Base refresh before planning. Local plan sessions refresh the base branch before the agent reads a single file, so a plan (including a Jira Intake refinement or investigation) is never written against a checkout that is behind origin or sitting on a leftover feature branch. In isolated mode the runtime fetches origin/<base>, checks the base branch out, and fast-forward pulls it. In current mode it only refreshes origin/<base> and leaves the checkout alone, because current mode records the checked-out branch as the working branch. Uncommitted changes fail the session before planning starts rather than being carried onto another branch — commit or stash them and start the run again. A session that already carries dirtyWorktreeApproval=approved is not blocked: it falls back to fetching origin/<base> and leaves the checkout — and the approved changes — exactly where they are. Repositories with no origin remote, bases that are not fetchable branch names (a raw SHA or refs/…), and paths that are not git repositories are skipped with a warning event on the run instead of failing; ephemeral sessions are skipped silently, since they have no repository to report on. Plan revisions do not re-run the refresh, so an approved plan keeps the checkout it was written against.

Create PR. Once the implementation is reviewed and the working branch has been pushed, the run detail composer shows a Commit to PR action. Clicking it queues a follow-up turn asking the coding agent to commit outstanding changes, push the current branch, and open a pull request workingBranch → baseBranch. Polyrepo work creates one linked PR for each changed repository in the configured workspace group. Once linked PRs exist, the composer also shows Check PRs, which queues a Flowman-aware review cleanup turn. For Cursor Cloud polyrepos, the follow-up includes every open linked PR URL, source branch, and base branch; the repository in each PR URL is authoritative even when the session GitHub URL points to the workspace root. That turn checks every linked PR, fixes actionable review feedback by default, commits with address review feedback, pushes each affected repository, and reports any remaining issues. Cloud runs show Check PRs as the only PR shortcut; Commit, Commit and push, and Commit to PR are hidden because the cloud provider manages commits, pushes, and PR creation during its run.

Preview changes. Preview sessions are stored separately from repository records because public zrok URLs are ephemeral. The run detail summary card and context panel show the target name, current status, URL when available, server ownership, heartbeat, and errors. Regenerating a preview supersedes the previous preview session for that target and creates a fresh zrok share without requiring the dev server to restart.

Complete PR. When GitHub reports that a linked PR was closed or merged, Flowman records the terminal pull request state from the webhook payload and marks the coding session done once every linked PR is merged or closed. For a local implementation started from Jira Intake, Flowman first queues the completion skill, which verifies the base branch and transitions the linked Jira issue to a Done-category status before completing the run. That matches the outcome of pressing Refresh PR status with a connected GitHub App. For local sessions, finalize also queues a runtime base_sync turn that fetches the base, checks it out, and fast-forward pulls when the worktree is clean — so the workspace leaves the merged feature branch. Dirty worktrees skip the checkout rather than clobbering local changes. If webhook delivery was disabled or missed, use Refresh PR status in Run actions on the run detail page as a manual fallback. When a polyrepo run still has an open sibling PR, finalize is skipped until the remaining PRs reach a terminal state.

Complete PR (cloud). Provider cloud runs have no connected local machine, so Flowman never queues the local completion skill for them. Cursor may create PRs natively for each repository it changes — including multiple repositories in a polyrepo Cursor Cloud workspace. Flowman records each reported PR against the repository encoded in its GitHub PR URL and shows repository identity with every linked PR on the run. It combines Cursor's structured branch response with PR URLs in the final summary. When a GitHub App is connected, Flowman also performs a bounded lookup for the shared Cursor branch across the configured workspace, recovering member PRs omitted from Cursor's response. Unrelated repositories are ignored and repositories Cursor did not change do not get a fabricated PR. If the initial implementation records at least one PR, Flowman publishes a durable coding.implementation.completed event only after every discovered polyrepo PR has been inserted. A managed trigger then starts one idempotent pull-request-ready Sub-agent. It uses the connected Flowman GitHub App to mark every linked draft ready for review and post a configured review comment (default @codex review) when no exact match exists; already-ready PRs are no-ops and terminal PRs are skipped. This child is independent: missing GitHub App access or a GitHub mutation failure leaves the implementation completed and exposes a retryable failed Sub-agent run. The parent does not wait for lifecycle delivery, so the child may start before or after the parent reaches its terminal state. If the Cursor stream ends before Flowman observes completion, an active Cursor Cloud implementation shows Check agent status in the run header. The user-triggered check is idempotent: a running remote run makes no writes, while a terminal run reconciles every discovered PR and updates the existing turn without polling or a background cron. Codex cloud requires the deterministic codex/... branch to contain a pushed commit, creates or updates a draft PR with the Flowman GitHub App, and fails actionably after one reconciliation attempt when no push exists. Cloud runs finalize from the GitHub webhook the same way local runs do. Merging or closing one linked PR does not complete the run while another remains open; once every linked PR is merged or closed (both are terminal), Flowman marks the coding run done. The manual Refresh PR status action remains available in Run actions when a GitHub App is connected and webhook delivery was missed.

Requirements. PR creation currently supports GitHub only (the provider is detected from the origin remote; other providers are rejected with a clear message). The coding-agent runtime host must have the GitHub CLI (gh) installed and authenticated (gh auth login or a GH_TOKEN/GITHUB_TOKEN environment variable).

Dirty worktree protection: before an implementation turn, the runtime runs git status. For configured polyrepo workspaces, the runtime checks the selected workspace root and members together. If the workspace worktree has uncommitted changes and the run has not been approved, implementation fails with DIRTY_WORKTREE_REQUIRES_CONFIRMATION and the session pauses awaiting approval. Reply to the failed run with a follow-up containing ALLOW_DIRTY_WORKTREE (case-insensitive) to requeue the same implementation on top of the existing changes; that approval message is consumed and does not create a chat turn. Run detail also exposes a Refresh worktree action that queues the local runtime to recalculate this aggregate status for existing coding runs, including completed polyrepo runs.

Future enhancement: a branchMode = "resume_previous" option (resume an earlier working branch) is reserved but not implemented in this version.

Email trigger mapping

IMAP email triggers can map a parsed request into this workflow without hard-coding a repository id. Email directives such as Repo: flowman-web and Plan-Mode: false are stripped from the prompt before dispatch.

repositoryName -> email.request.repositoryName
prompt         -> email.request.prompt
planMode       -> email.request.planMode
attachments    -> email.workflowAttachments

# Optional fixed-repo alternative:
repositoryId   -> static registered repository id

Question format

Codex must ask clarification questions as multiple-choice options. Every option includes a hint so the review modal can present a clear tradeoff before the user clicks Next or Submit. The modal also supports a final “Something else” option for each question so users can provide a custom note when no choice fits.

<flowman_questions>
{
  "questions": [
    {
      "id": "scope",
      "text": "Should this be project-scoped?",
      "options": [
        {
          "id": "project",
          "label": "Project-scoped",
          "hint": "Use when each Flowman project can choose different repos."
        },
        {
          "id": "global",
          "label": "Global",
          "hint": "Use when one shared behavior applies everywhere."
        }
      ]
    }
  ]
}
</flowman_questions>

Plan revisions

When Codex returns a plan, reviewers can approve it, reject the workflow, or request changes from the review modal. Approval queues a Codex implementation turn in the same thread. Approval and rejection use the same human decision resume path as standard Approvals: Flowman posts the decision to the Workflow SDK webhook and persists it in Convex so the review UI leaves the pending state. Revision requests keep the same Codex planning thread and send the current plan plus reviewer instructions back to the runtime. The latest returned plan replaces the previous plan for the next review cycle.

To prevent local workstation conflicts, approval is blocked when the same repository already has a local coding session in the Kanban Implementation or Review columns. The plan stays ready for review, so the same approval can be retried after the blocking session is marked done. This guard is skipped when the coding session has no repository configured, and when location is cloud — provider cloud runs use isolated environments, so multiple cloud implementation runs on the same repository can proceed concurrently.

Implementation and chat

Planning and revision turns run in Codex plan mode and must not mutate repository files. Once the plan is approved, or immediately when planMode is false, implementation and follow-up chat turns run in default mode with workspace write access to the selected repository and registered sibling repositories for the runtime environment. The workflow completes after the implementation turn succeeds; later follow-up chat keeps using the same Codex thread but does not reopen the completed workflow run. Follow-up chat can be queued after successful implementation, after implementation failures, and while the run is already terminal as long as the coding session still has a Codex thread id.

Direct implementation starts also use the repository conflict guard for local execution. When planMode is false and the selected repository already has active local Implementation or Review work, Flowman rejects the start before opening a run. Cloud direct starts (location: "cloud") are not blocked by other sessions on the same repository. Starts without a registered repository are treated as ephemeral and are not blocked by this guard.

Implementation and follow-up turns store structured Codex activity from the app-server or OpenAI Responses stream. Flowman renders assistant messages, safe reasoning summaries, command output, tool/file-change activity, and changed-file summaries separately. The executor also writes a lightweight progress heartbeat while a turn is active so the implementation block does not look stuck when Codex has not emitted user-facing text yet. Raw hidden reasoning is not shown; only Codex-provided summary/progress events and Flowman runtime heartbeats are displayed.

Implementation and follow-up turns also write token usage to agentUsage when the Codex app-server or OpenAI Response reports usage counters for the completed turn. If the provider omits usage metadata, Flowman stores the turn output and activity normally, but the dashboard token chart has no token counts for that turn.

Plan mode can run while another implementation has the repository dirty or changes files during inspection. Flowman treats those worktree changes as external context and continues planning when Codex did not emit file-change activity for the planning turn. If Codex emits file-change or diff activity during plan mode, Flowman treats that as a planning violation before approval.

When attachments are present, runtime polling includes fresh Convex file URLs. The local coding-agent runtime downloads the files into a temporary directory outside the repository and appends the local paths, original names, content types, and sizes to the Codex prompt. If a file cannot be downloaded, the coding turn fails with that download error rather than silently running without the attachment.

Failure behavior

Cancelling a run from its detail page stops an active Cursor Cloud run first, then cancels the durable Vercel Workflow, and only records the Flowman run as cancelled after both remote operations succeed. If a provider cannot confirm cancellation, Flowman reports the error and leaves the run retryable instead of showing a false cancelled state. Local coding-agent sessions continue to receive an interrupt signal when the local cancellation is committed.

Planning or implementation runtime failures mark the session and run failed. In plan mode, Codex must finish with a structured <flowman_questions> or <proposed_plan> block; unstructured status text is kept as raw output and fails the planning session instead of being shown for approval. Rejecting questions or the plan resumes the workflow webhook with a rejected decision, records the reason when provided, and closes the run as failed. After an implementation failure, reviewers can either retry the failed implementation turn or queue a follow-up chat turn in the same Codex thread with revised instructions. Follow-up chat failures are stored on the coding session without changing the completed run.

Failed plan-mode sessions that already have a Codex thread can be continued from the run detail page. The continuation stays in plan mode, uses the original task plus optional reviewer instructions, and reopens the run while Codex produces questions or a replacement plan. Failed coding-agent runs also keep the initial prompt visible in the run detail so the recovery action has the original context.

OpenAI cloud failures distinguish missing project credentials, unavailable GPT-5.6 access, GitHub App permission/repository access, expired containers, provider cancellation, and a missing pushed commit. In-progress Responses remain pending. Flowman keeps the initial event stream attached until OpenAI starts processing, then uses polling and resumable streams for subsequent bounded action windows. If a Response stays queued for 90 seconds, Flowman cancels it, creates a fresh conversation and phase container, and retries once with a new idempotency attempt. A second 90-second queue timeout fails with an actionable error instead of waiting for the container to expire. Transient retrieval failures retry and terminal state is reconciled from the Responses API before Flowman persists failure. Flowman never silently falls back to another model.