DeepSeek Harness subagents: product-error, stale entries

DeepSeek Harness (DSH)'s subagents have a clear gap between "very convenient when they work and very hard to diagnose when they break". This batch of threads has four typical forms: failure returns only one line, Product subagent failure (product: Codex; stage: turn; category: product-error), with no underlying detail; the same task completes with the Codex CLI but fails with subagent_codex (the bundled Codex is older than the user's config); after deleting the subagent's session directory the UI entry still cannot be cleared; and the most severe one — a continuable subagent throws while reading the inbox at the settle stage and takes the whole process down as a fatal exit (exit 1), reproducing after about a dozen minutes. The first three are "diagnosable but with a threshold", the last is a "stability problem" and has the highest priority (#9640, #9346, #9552, #8849). Also, if a subagent's symptom is that the control-class tools act as if they were swapped and addressing by id fails, that belongs to the separate "tools replaced by the Team build" family — see DeepSeek Harness: duplicate list_agents, stuck subagents.

DSH plugin only product-error: details are folded away at the projection stage

The one-line conclusion: the adapter folds several different underlying errors into product-error together, discarding the real error identifier at that step; the diagnostic rendering then outputs only fixed fields — although the full cause is still kept on the failed instance, nothing reads it. So what you get is always a category name with no information (#9640).

DSH plugin four steps to fish out the details

1. First confirm "the same task succeeds through a different entry point": if the same task completes when run directly with the Codex CLI, the problem is in the adapter layer's communication/classification, not the task itself (#9640).
2. Capture the app-server traffic. The community plugin @argszero/dsh-codex-wire-capture tees and saves the app-server's stdout, thereby capturing the folded-away codexErrorInfo (#9640):

npm i @argszero/dsh-codex-wire-capture

3. Look up the meaning of the error identifier you got, then decide whether it is an unsupported model, an invalid parameter, or a failure caused by an upstream rollback (#9640).
4. Read the boundary of stage: turn: it can only tell you "the failure is in this round's execution stage", and cannot substitute for the specific error; seeing it should not stop you (#9640).

DSH plugin version mismatch: bundled Codex is older than your config

The one-line conclusion: subagent_codex reuses the local Codex config file (for example the default model name), while the host's bundled Codex binary may be an older version that cannot read that model, so it fails at startup or on the first round — the same task succeeds with the CLI precisely because it uses your newer local version. (#9346) This kind of "the subagent runs a model or version different from what you assumed" mismatch (including model inheritance and reasoning effort not propagating) is covered in more detail in DeepSeek Harness subagent inherits the wrong model.

DSH plugin diagnostic quartet (align these four and the problem usually shows immediately)

1. The resolved executable path: confirm which Codex the subagent actually calls, not the one you assume.
2. Its version number: run codex --version directly and compare it with the host's bundled version.
3. The effective CODEX_HOME: confirm which config file is read (there may be several on the same machine).
4. The resolved model name: compare the default model declared in the config file against "the models that version supports" (#9346).

DSH plugin three ways to handle it

1. Make the subagent use only a model the bundled version supports (temporarily usable, smallest change) (#9346).
2. Switch to a newer Codex executable: the workaround given in the thread, already verified on Windows, is to back up and rewrite the function in the plugin that constructs the Codex launch arguments so it points to a newer Codex (this is a local edit and will be overwritten when you upgrade the plugin) (#9346).
3. Verify: rerun the same task, expecting the subagent to start and complete normally; if it still fails, return to the quartet and keep aligning (#9346).

DSH plugin: deleted the session directory, the UI entry remains

The one-line conclusion: the subagent record is now "a catalog event written into the parent session log + a projection", and none of the four layers — event, projection, query, and tool — has a removal path — the record is append-only, so deleting the on-disk directory does not make the UI entry disappear. The thread ran a comparison on the same UUID: doing this in August worked, but from October (0.2.0-rc.2) on it does not (#9552).

DSH plugin handling

1. Confirm the criterion: after deleting the subagent's session directory, neither refresh nor restart clears the entry; yet the workspace list and the session file itself are normal (#9552).
2. There is no user-side workaround for now: the thread states explicitly that a plugin cannot do it either — the fold logic ignores other event types, and a client plugin can at most do a display-layer hide (#9552).
3. An acceptable alternative: archive or rename the subagent sessions you no longer need, and use "filter/sort" to reduce the noise, rather than trying to delete the record.
4. The requested direction (for upstream feedback): add a subagent/retire-style event + filter it during folding + have query and tools follow (#9552).

DSH plugin settle-time exception crashes the whole process

The one-line conclusion: when a continuable subagent reads the inbox at its settle stage, the read function throws directly when the state yields no value, and the settle logic that calls it is an uncaught async immediately-invoked function — the exception escapes as an unhandled rejection and the whole process exits fatally. The tell is that it reproduces after about a dozen minutes and the crash stack maps to two source locations, the inbox read and the settle activation (#8849).

DSH plugin four steps to handle it (by priority)

1. Confirm the criterion: the host exits without warning after a dozen or so minutes with exit code 1; the logs show an unhandled rejection whose stack points to the inbox read and the settle activation (#8849).
2. Workaround (currently the only effective one): roll back to an older version that does not enable the continuation / activation mechanisms — the problem is on that settle path (#8849).
3. When rollback is impossible: use an external supervisor process to restart it automatically, downgrading "unusable" to "recoverable"; but note this interrupts all in-flight sessions (#8849).
4. Remember two layers of defect: one, the read path should not throw when the state is undefined; two, the top-level async immediately-invoked function must have a fallback. The thread also notes that "missing logs" is itself a defect, because there is no usable clue before the crash (#8849).

DSH plugin troubleshooting notes

The recommended troubleshooting order for subagent problems: rule out "process-level stability" first (will it exit on its own), then "version mismatch", and only then "insufficient diagnostic information". Eight points:

1. An exit that reproduces after a dozen minutes should be treated as a fatal exit first, not spent on diagnosing the message text (#8849).
2. product-error means "classification failed", not "product defect" (#9640).
3. stage: turn only narrows the scope, it does not locate the cause (#9640).
4. "CLI works, subagent does not" is the fingerprint of a version mismatch (#9346).
5. The diagnostic quartet must be read together: executable path, version, CODEX_HOME, and model name; missing any one makes misjudgment easy (#9346).
6. A local edit to a plugin file will be overwritten on upgrade; write it into your own change list (#9346).
7. The subagent record is append-only: deleting the directory ≠ deleting the record, so stop expecting a restart to clear the UI entry (#9552).
8. State the fix status honestly: all four are unfixed in the version discussed (0.2.0-rc.2); the community plugin can patch diagnostics (capture the wire), but version mismatch, entry retirement, and settle crash all need core-side changes.

Subagent problems like these are often directly tied to "what is installed and at what version", especially the version-mismatch item. Instead of typing commands everywhere to compare versions, use a visual marketplace like DSH Plugin Hub: the installed list carries version numbers and source markers, and install/uninstall history and system logs sit in one panel, so you first confirm "what version each component in this environment is".

Source: Discussion #9640, Discussion #9346, Discussion #9552, Discussion #8849.