Sub-agent completion polling fails with "unknown job" during multi-agent task, halting generation mid-task

[theoriginalsam]

Environment:

• @deepseek-ai/dsh version 0.1.1-rc.2 (latest)
• Node.js v22.23.2
• Custom OpenAI-compatible provider (self-hosted vLLM serving Qwen/Qwen3.8-27B)
• macOS, run via npx @deepseek-ai/dsh web --no-open

Steps to reproduce:

1. Configure a custom provider pointing at any OpenAI-compatible endpoint.
2. Ask the agent to do something large enough that it plans a multi-file task with parallel sub-agents — in my case: "write a 200 page book on Quantum Machine Learning with all the necessary topics, easy to read, simple english".
3. The agent correctly plans the task (style guide → outline → parallel chapter-writing sub-agents → assembly), and most sub-agents complete successfully — real content gets written to disk (7 of ~9 expected chapter files, ~21k words, plus style-guide.md, OUTLINE.md, front-matter.md, two appendices).
4. At some point, the agent attempts to wait on what looks like a sub-agent using a tool intended for background shell jobs instead:

   {
     "job_id": "7576042c-f6d8-47e9-a158-120eb8a4b245",
     "wait": true,
     "timeout_ms": 300000
   }

   which immediately returns:

   Error: unknown job 7576042c-f6d8-47e9-a158-120eb8a4b245
   

5. The turn ends there with no recovery/retry. The task never completes — the final assembly step (build.sh) never runs, and at least one chapter (chapter 2) and one chapter's second half (ch05 part b) are simply missing, with no error surfaced to the user beyond the stalled UI.

Expected: either the correct tool/mechanism is used to await sub-agent completion (the model's own reasoning trace shows it recognized the mismatch: "job_output is for background bash jobs, not for sub-agents. The sub-agent completion will arrive as a runtime notification. I'll end the turn and wait." — but then nothing further happened), or a failed/missing sub-agent should be retried or surfaced as a visible error rather than silently stalling the whole task.

Actual: partial output (~21k words of real content) with no indication to the user that anything failed — the chat just stops.

[denial123789]

The rc.2 source clarifies one important point: job_output is the intended collector for a one-shot background subagent. The mismatch is the identity supplied to it.

tool-subagent exposes three routes:

• foreground: result returns inline; its internal runId is not a Job handle;
• one-shot background: acknowledgement is exactly started background subagent job <jobId> and the registry ID shape is <kind>-N (normally subagent-N);
• continuable background: acknowledgement is started subagent <subagentId>; settlement notice and send_message own that child lifecycle.

The UUID in the report is therefore not a canonical rc.2 Job Registry receipt. unknown job is expected if a run/child ID is passed to job_output, if the parent Agent already disposed (owned jobs are then removed), or after a Host restart. job_list from the same live parent is the authoritative set of collectable handles.

For partial output, the safe recovery is to freeze exact acknowledgements, reconcile files against the planned deliverable manifest, rerun only missing/invalid units to disjoint paths, and block final assembly until every required input passes. I documented the route table and recovery checklist here: https://sandbaseai.github.io/deepseek-harness-handbook/subagent-unknown-job.html

Disclosure: I maintain the SandBase community handbook.

[theoriginalsam]

Thanks for the detailed correction — appreciate the pointer into the actual routing logic. I went and checked this against the source directly (packages/subagent/tool-subagent, packages/jobs/tool-jobs, and the relevant .agents/notes architecture docs) rather than taking either of our accounts at face value, and can confirm:

job_output/job_list/job_kill are indeed the correct, kind-agnostic tools for background bash jobs and one-shot background subagents — my original framing ("wrong tool for a subagent") was incorrect.
One-shot background subagent job IDs are canonically shaped subagent-N (confirmed in tool-subagent.spec.ts: started background subagent job subagent-1).
job_output throwing unknown job for an ID outside the registry is expected/correct behavior for that function in isolation.
So the actual defect is more specific than I first reported: the ID the model attempted to poll (7576042c-f6d8-47e9-a158-120eb8a4b245, a raw UUID) doesn't match the harness's real ID format at all. This looks like the model (Qwen3.8-27B in my case) fabricating a plausible-looking identifier instead of correctly recalling the actual subagent-N id it would have received when the subagent started — a model-side context-tracking failure rather than a harness tool-routing bug.

That said, there's still a legitimate harness-level question worth keeping open: when job_output is called with an id absent from the registry, should the failure response nudge the caller to check job_list for the real handle before giving up, rather than just erroring and letting the turn end there with no recovery? In my case the whole multi-file task (a partially-successful "write a book with parallel chapter subagents" run) stalled permanently on this single bad ID, losing one chapter and the final assembly step, with nothing surfaced to the end user beyond a frozen UI.

Appreciate the correction either way — updating my own notes accordingly.

[weijiafu14]

@denial123789's identity analysis is right, and I want to add the half that explains why the run stalled rather than just errored — because your model's reasoning trace is the most important evidence in this report and it has been read as a mistake when it was not.

The model did exactly what DSH told it to do. Its trace says: "job_output is for background bash jobs, not for sub-agents. The sub-agent completion will arrive as a runtime notification. I'll end the turn and wait." That is not the model guessing — it is repeating DSH's own tool description back at you. tool-subagent's prompt text says, verbatim:

When that run settles, the runtime sends the parent a notice containing its outcome and any final assistant message.

So after the wrong-identity error, the model recovered correctly, ended the turn, and waited for a promise the tool had made. Then nothing arrived. That second half is the real bug in this report, and it is separate from the job_output/UUID mix-up.

And the mechanism does exist, which narrows it usefully. The continuation manager is documented as owning "settlement delivery to the parent", and the delivery lands in the parent's inbox — the file states plainly that "The Agent inbox is the only turn queue." So a settled child should have woken your parent with a new turn, with or without a goal armed.

One concrete thing to check, which splits this into two very different bugs. That same file logs a specific warning when delivery fails:

subagent "<childId>" settlement notice was not delivered to its parent: …

Grep your logs for settlement notice was not delivered.

• Present → the child settled and the notice was lost on delivery. That is a delivery bug, and the warning names the child.
• Absent → the child never settled at all, so no notice was ever due. Then the question is what happened to the two missing units (chapter 2 and ch05 part b) — which lines up with your file evidence: 7 of ~9 chapters landed, and the missing ones are plausibly the children that never reached settlement.

Either way it is worth adding to the report, because right now the title says "polling fails with unknown job" and the actual stall may have nothing to do with polling.

Related, and worth cross-linking: #4715 and #4664 are the same seam from the opposite direction — there, a parent that goes idle with outstanding work gets woken too aggressively (the goal-round driver re-arms on every idle, producing empty rounds). Yours is a parent that goes idle with outstanding work and is never woken. The continuation source even documents the window in between: Agent.status is still idle between followup() and the accepted turn. Whoever looks at "what should happen when an agent is idle with work outstanding" should have all three threads in front of them.

On your "Expected" section: I would add a third option to your two. Even with delivery fixed, a child that fails or never settles currently produces no user-visible signal — the chat just stops. #4666 is asking for the adjacent piece (SubagentResult.diagnostic is never populated, so the parent sees a bare Error: subagent run failed). Your case is worse, because there is not even a bare error. "A failed sub-agent should be surfaced" is the ask that would have saved you the file-by-file reconstruction.

Interest disclosure: I maintain a third-party DSH plugin and ship subagent functionality through it, so I am not a neutral party on this topic — which is why I am pointing only at DSH's own source and your own trace. The native subagent runtime is DSH's; we do not touch it and could not fix any of this.