afx: no way to pass harness runtime flags (e.g. opencode --auto) via .codev/config.json; --builder-cmd fails silently

[pseudoseed]

Problem

There is no supported way to pass harness-specific runtime flags to a spawned builder. --harness selects the agent and --model pins the model, but anything else the harness's CLI exposes is unreachable from both the CLI and .codev/config.json.

The concrete case: opencode has a --auto flag ("auto-approve permissions that are not explicitly denied"). A builder spawned with --harness opencode prompts for permission on every ordinary command — porch, git, print, ls — which makes strict-mode protocol runs impractical to babysit. There is no way to express "spawn this builder with --auto".

Why the existing escape hatches don't cover it

--builder-cmd is the wrong tool and fails silently. It bakes a literal command string into .builder-start.sh, and afx still appends its Claude-shaped --prompt "$(cat ...)". For a harness whose CLI takes the prompt positionally, the prompt is lost. With opencode run [message..] (no --prompt flag) the result is:

• opencode receives an empty message and exits instantly
• the loop in .builder-start.sh relaunches it forever
• afx tower log shows socket missing or lstat error
• nothing fails at spawn time — afx status happily lists the builder, so it looks like it worked

This cost real time to diagnose. --model's own help text already articulates the principle being violated here:

Resolved into the harness's own flag rather than baked into a command path.

That is exactly right, and it is why --builder-cmd should not be the answer for runtime flags either.

Custom harness config doesn't cover it. validateCustomHarnessConfig requires roleArgs and roleScriptFragment, both of which are role-injection concerns (roleArgs is passed through expandTemplateVars(arg, content, filePath)). There is no field for "extra args to append at launch", and defining a whole custom harness just to add one flag to a built-in one means duplicating the built-in's prompt/model/worktree-file behaviour.

Per-harness config files are a partial workaround only. opencode reads a permission block from the worktree's opencode.json, which getWorktreeFiles already generates for role injection:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [".builder-role.md"],
  "permission": {
    "bash": { "*": "allow", "kubectl delete*": "ask" },
    "edit": "allow"
  }
}

This works, but afx regenerates opencode.json on every spawn, so the block is lost on respawn and has to be reapplied by hand. It also only helps harnesses that happen to have file-based config.

Request

Add a way to declare harness runtime flags in .codev/config.json, applied at launch and surviving respawn. Rough shape:

{
  "shell": { "builder": "claude" },
  "harness": {
    "opencode": {
      "builderArgs": ["--auto"]
    }
  }
}

with an optional per-spawn override:

afx spawn 484 --protocol spir --harness opencode --model x-ai/grok-4.6 --harness-arg --auto

Design notes:

• Should extend a built-in harness, not require redefining one. Today harness.<name> is only reachable as a full custom definition.
• Should compose with --model and --prompt rather than replacing the generated command, so the buildScriptPromptArg / buildModelArgs logic still applies.
• Consider merging into getWorktreeFiles output for file-configured harnesses (opencode's permission block) rather than only argv, since some settings have no flag equivalent.

Secondary: fail loudly on a broken builder command

Independent of the above, the silent-death mode is worth fixing on its own. When a builder's process exits immediately and repeatedly, afx status should not report it as a healthy implementing builder. A restart-loop detector in session-manager.ts (e.g. N exits under M seconds → mark the builder failed and surface the harness's stderr) would have turned a multi-step investigation into a one-line error.

This matches the project's own "silent success is the default failure mode" lesson: the exit status said fine while nothing was running.

Environment

• afx from pseudoseed/codev (local checkout ~/dev/codev-1455)
• opencode v1.18.18, model x-ai/grok-4.6
• Relevant source: packages/codev/src/agent-farm/utils/harness.ts (validateCustomHarnessConfig, buildScriptPromptArg, buildModelArgs, getWorktreeFiles), packages/codev/src/agent-farm/cli.ts:317-318

[pseudoseed]

Third instance of this same root cause, from the same builder run. Adding it because it argues the gap is structural rather than a missing flag.

A --harness opencode builder reached a protocol boundary where porch emitted a context-refresh task, and reported:

enter:plan self-refresh REFUSED — harness opencode has no in-session context reset.
Keeping context and continuing to plan.

The builder behaved correctly — builder-refresh is designed to refuse rather than clear unsafely, and it refused loudly instead of silently pretending. But the refusal is permanent for this harness: opencode has no /clear equivalent, so a long protocol run on opencode can never refresh, and there is no way to express that in afx.

So the running tally of Claude-shaped assumptions in the harness abstraction:

1. Prompt delivery — afx appends --prompt; opencode run takes the message positionally. Fixed by --harness/--model, but --builder-cmd still fails silently this way.
2. Permission / auto-approve — no way to pass --auto or a permission policy (the original report above).
3. Context refresh — no way for a harness to declare that it cannot do an in-session reset, so porch schedules a task that can only ever be refused.

Suggestion: the harness interface already models capability-absence well in one place. buildModelArgs is documented as:

Optional, and absence is meaningful: it declares "this harness exposes no model selector". assertHarnessAcceptsModel turns that into a loud error rather than letting --model be silently dropped.

That is the right pattern. Extending it — e.g. an optional supportsContextReset / buildContextResetCommand — would let porch skip or re-plan the refresh for harnesses that cannot do it, instead of emitting a task that is guaranteed to be refused. Same idea for runtime args: an explicit declaration beats a command-path override that silently loses the prompt.

Not blocking; the builder is proceeding with accumulated context and its state is persisted to codev/state/<id>_thread.md, so a --resume respawn is the fallback. Filing it so the three land together.

[pseudoseed]

Fourth instance, and this one caused a real loss of control rather than just friction.

The af-mailbox stuck-composer escalation fires at roughly a 3 minute hold. On an opencode builder, normal turns routinely exceed that: a consult run in this project took 580s, and ordinary implement turns run 10+ minutes at 40-60% CPU. So the escalation fires constantly on a perfectly healthy builder.

Two consequences, in order of severity:

1. It desensitises, and then a real one is missed. Today an architect sent a builder a hard limit forbidding it from running an irreversible maintenance window (stop k3s, prune the live datastore, VACUUM) on a production control plane. That message sat held while the builder was in consult. The architect saw the STUCK escalation, judged it another false positive based on the previous two, and chose not to interrupt. The builder ran the window before the instruction arrived. Production survived only because unrelated earlier work had already moved CoreDNS off that node.

The escalation was correct that time. It had cried wolf enough to be discounted.

2. held (busy) and stuck are not distinguishable to the caller. Both surface the same way. There is no signal for "this builder is genuinely mid-generation" versus "this composer will never clear", so the only safe response to any hold on an important message is to interrupt, which ends the builder's turn and discards its in-flight work.

Suggestions:

• Scale the escalation threshold to observed turn length per harness, or make it configurable, rather than a fixed short timeout tuned to Claude Code's cadence.
• Distinguish busy-with-progress from wedged. Builder process CPU or worktree file mtime would separate them cheaply.
• Consider a priority flag on afx send so a caller can mark a message as must-deliver-before-next-tool-call, rather than forcing the interrupt-or-wait choice on every message regardless of stakes.

Same root cause as the three above: the harness abstraction is calibrated to Claude Code's behaviour, and other harnesses fall outside the assumptions in ways that fail quietly.