[jahvon]

Summary

Fixes a batch of problems agents and people hit running flow through Mochi. Most of them cost an agent a retry or led it to a wrong conclusion: a check that exited non-zero came back as a tool error, a remove with nothing on stdin "succeeded" without removing anything, a push to a git workspace silently didn't reach --sync, and a git workspace holding only flow files couldn't reach the repository it operates on.

Notable Changes

• MCP results: execute, run_command, run_python and run_executable return a run that started and finished as a normal result (output, exitCode), whatever the exit code; only a run that never started is an error. Output has CRLF normalized and carriage-return redraws reduced to their last frame.
• list_executables include_args: adds each executable's positional args, flags with type and default, required markers, and prompt params, so an agent needs no get_executable per task. A prompt param left unanswered over MCP names its question and says to pass it in params.
• Checkout binding: flow workspace checkout NAME PATH (or workspace add --checkout) binds a git workspace to the local clone its executables operate on, stored in user config. A dir of @ or @/sub resolves there, and runs get FLOW_CHECKOUT_DIR. When the caller is inside the same repository or one of its worktrees, the caller's working tree wins.
• exec --dry-run / MCP dry_run: prints the resolved args, params, dir and command without running anything, resolving secrets, prompting, or creating temp dirs, so it is safe for an untrusted workspace.
• Sync pulls git workspaces: flow sync, the global --sync flag and MCP sync fast-forward git-sourced workspaces before rescanning; one that can't be pulled is named and skipped. --no-git rescans without the network (write_flowfile's post-write refresh uses it), --git is deprecated, and --force no longer needs it.
• Env: an unset $VAR in an arg default expands to empty, as in a shell. A missing env file is skipped with a warning instead of failing the run or dropping the other files.
• CLI: confirmations without a terminal read a line from stdin, and no answer is a usage error asking for --yes (it exited 0 having done nothing). browse --list --workspace lists all of that workspace's namespaces. A verb and ref passed as one quoted argument get the split form suggested. The private-executable error points at --workspace. cache help no longer calls persistent values temporary.

Breaking changes are recorded under v2.5.0 in docs/breaking-changes.md.

flowchart LR
  subgraph run["flow <verb> <ref>"]
    R[resolve executable] --> D{--dry-run?}
    D -- yes --> P[print plan: env, dir, cmd]
    D -- no --> E[build env + checkout] --> X[run]
  end
  C[(user config<br/>gitWorkspaces.checkout)] --> E
  W[caller cwd<br/>same git common dir?] --> E

Loading

[codecov]

Codecov Report

❌ Patch coverage is 58.08656% with 184 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cmd/internal/workspace.go	27.71%	57 Missing and 3 partials ⚠️
cmd/internal/dryrun.go	45.67%	39 Missing and 5 partials ⚠️
internal/mcp/tools_executable.go	74.02%	14 Missing and 6 partials ⚠️
cmd/internal/sync.go	44.82%	14 Missing and 2 partials ⚠️
cmd/internal/helpers.go	51.72%	12 Missing and 2 partials ⚠️
internal/services/git/checkout.go	70.96%	5 Missing and 4 partials ⚠️
internal/utils/env/env.go	75.00%	3 Missing and 4 partials ⚠️
cmd/root.go	71.42%	4 Missing ⚠️
cmd/internal/browse.go	50.00%	2 Missing ⚠️
cmd/internal/exec.go	85.71%	2 Missing ⚠️
... and 3 more

📢 Thoughts on this report? Let us know!

[jahvon]

Status: Done. Mochi picks this up in flowexec/mochi#406 (pinned to this branch's commit; re-pin after merge).

Try it

git fetch origin && git switch fix/mochi-reported-issues
flow build binary
.bin/flow <verb> <ref> --dry-run -- <args>

Verification

• Verified: flow validate passes: generate, lint, unit and e2e tests, schema validation.
• Verified by hand with a dev binary and a sandboxed config: --dry-run prints args, params, <secret>/<prompt> placeholders, missingPrompts and the @ dir. An unset $VAR default expands to empty. A missing envFiles entry warns. An MCP-sourced run with an unanswered prompt names the question. workspace remove </dev/null exits 2 asking for --yes, echo no | aborts with 0, and echo yes | removes. The joined "verb ref" hint appears. browse --list -w lists non-root namespaces.
• New specs: checkout resolution against a real repo and worktree, @/ dir expansion, MCP result shape for non-zero exits, carriage-return normalization, include_args, LoadEnvFromFiles skipping missing files, the no-answer confirmation, and the dry-run e2e.
• Verified: git workspace e2e specs run plain sync and sync --force against a local bare repo, and a new spec checks sync --no-git leaves the clone untouched.
• Not verified: sync against a real network remote, and the checkout binding from the Mochi desktop app.

Risks

• Breaking changes are listed under v2.5.0 in docs/breaking-changes.md. MCP clients that keyed failures on isError need to read exitCode.
• --sync now does network I/O for git workspaces. A failed pull is a warning and doesn't stop the run.