Adopt qwen_dispatch as a nexus agentic-dispatch operator (RDR-008)

[Hellblazer]

Summary

The qwen-coprocessor-stack supervisor publishes qwen_dispatch (RDR-008): an MCP tool that runs one bounded agentic coding task on a local-Qwen agent and returns an AgentResult. This proposes nexus adopt it as a typed agentic-dispatch operator — the agentic counterpart to nexus's retrieval operators (search/extract/rank/…) — usable as a plan step (plan_run) and matchable (plan_match).

Full contract lives in the qwen-coprocessor-stack repo: docs/contracts/qwen-dispatch-operator-contract.md + golden fixture docs/contracts/fixtures/qwen-dispatch-shapes.json. Adoption = conforming to the fixture, not sharing code (same posture as RDR-007's agent-dispatch contract).

Proposed operator signature

operator qwen_dispatch:
  input:
    prompt:      string          # required — task statement
    worktree:    string (abs)    # required — caller-supplied tree the agent edits
    base_commit: string          # required — patch diffed vs this, NEVER HEAD
    max_turns?:   int            # default 50
    min_tokens?:  int            # default 16384
    timeout_ms?:  int            # default 1_800_000 (milliseconds)
    provider_id?: string         # pin a declared provider (overrides agent_kind)
    agent_kind?:  string         # dispatcher family, default "qwen-local"
  output (AgentResult):
    patch:   string              # source-only diff (test paths stripped)
    turns:   int                 # 0 on qwen-local success until qcs-j2r lands
    outcome: "completed" | "timeout" | "turn_limit" | "error"
    cost:    number              # 0 for free-local
  error:
    { code: "no_provider" | "missing_agent_kind" | "unregistered_kind" | "shutting_down",
      message: string }

What nexus must know (normative)

1. Strictly one-shot — no resume path. A session reaching idle is terminal. nexus MUST NOT design a resume-the-executor continuation against this operator. Continuations (suspend/resume, elicitation, sampling, choice injection) are engine concerns: implement them in the nexus engine and call qwen_dispatch for the leaf agentic work. The executor never pauses or yields mid-run.
2. The engine owns the worktree + base_commit. Default strategy is caller-supplied worktree: nexus passes a ready worktree path + its base_commit; lifecycle (create/cleanup) is nexus's. The executor only runs + extracts.
3. Registration ceremony. The executor host declares an agent-cli provider (agent_providers config) and registers a DispatcherKind → Dispatch. On the nexus side, the analogous step is registering qwen_dispatch as a typed operator keyed to the shapes above.
4. turns caveat. turns is 0 on a qwen-local success run until qwen-coprocessor-stack-j2r emits turns_completed on the success poll. Don't build plan logic that depends on a meaningful turns on success yet.

Out of scope (this proposal)

The nexus workflow engine, plan library, plan_save capture, and the continuation machinery — those are nexus's to design. This proposal states only what the executor provides and requires.

Acceptance

• nexus agrees the operator signature above (or proposes amendments).
• The qwen-coprocessor-stack side is pinned by qwen-dispatch-shapes.json + a conformance test (landed in RDR-008 P3).

---

Source: qwen-coprocessor-stack RDR-008 (Agentic dispatch executor), bead qwen-coprocessor-stack-pwa.

[Hellblazer]

Update: turns now carries the real completed-turn count on success (qcs bead j2r — PollResult.turns_completed is an always-present live counter). The earlier 'turns=0 on qwen-local success until j2r' caveat in the proposed signature above is retired; the proposal/spec/conformance-fixture in qwen-coprocessor-stack have been updated accordingly.

[Hellblazer]

Contract revision v2 (qcs bead dps). The qwen_dispatch operator gains a worktree-spec selector: supply exactly ONE of worktree (caller-supplied path) or repo (owner/name — the executor materializes a per-instance worktree at base_commit and cleans it up). worktree is therefore now optional; repo/repo_url are added; a new error code invalid_worktree_spec covers the neither/both case. base_commit stays required in both modes. Please review v2 (this signature), not the original v1. The qcs-side contract doc + golden fixture + conformance test are updated in lock-step.

[Hellblazer]

Contract update — v3 (RDR-009): operator output is now Artifact[], not a single patch

RDR-009 (Generalized harvest envelope) is implemented and merged in qwen-coprocessor-stack. It changes the qwen_dispatch operator's output shape, so the proposed nexus operator signature here needs a corresponding revision before adoption.

What changed

The response is no longer AgentResult = {patch, turns, outcome, cost}. It is now:

output (AgentResult):
  artifacts:  Artifact[]   # was: patch: string
  turns:      int
  outcome:    "completed" | "timeout" | "turn_limit" | "error"
  cost:       number       # USD; 0 for free-local

Artifact is a four-kind tagged union (kind discriminant):

Artifact =
  | { kind: "patch";  diff: string;  base: string }
  | { kind: "value";  value: unknown;  schema?: string }
  | { kind: "entity"; type: "bead"|"link"|"rdr";  id: string;  op: "created"|"updated" }
  | { kind: "tier";   tier: "T1"|"T2"|"T3";  key: string }

A qwen_dispatch coding run emits one {kind:"patch", diff, base} (the git-diff harvester, source-only, diffed vs base_commit — never HEAD). The other three kinds are produced by the PUSH-channel /accept harvester (out of executor scope; engine concern). The request shape is unchanged (the v2 worktree XOR repo selector + invalid_worktree_spec still stand).

Impact on a nexus plan step

• A step that previously read $stepN.patch must now read $stepN.artifacts and filter by kind, e.g. $stepN.artifacts[?kind=='patch'].diff | [0] (JMESPath). There is no transition shape — the wire change is hard.
• A leaf's Artifact[] is a natural plan_run step-output value ($stepN.artifacts), so the ledger = nexus step output posture (RF-4) is unchanged; nexus still owns persistence via plan_save. No nexus code is shared — adoption = conforming to the fixture.
• Inline filtering like $stepN.artifacts[?kind=='entity'] depends on the JMESPath template engine (nexus-owned) — flagging as the one open design sub-point.

Authoritative sources (qwen-coprocessor-stack, merged)

• Contract (prose, v3): docs/contracts/qwen-dispatch-operator-contract.md
• Golden fixture (response shape): docs/contracts/fixtures/qwen-dispatch-shapes.json
• Artifact-union fixture: docs/contracts/fixtures/agent-shapes.json (artifact section)
• RDR: docs/rdr/RDR-009-harvest-envelope.md (status: closed/implemented) + post-mortem docs/rdr/post-mortem/009-harvest-envelope.md

No action required of nexus beyond acking the revised output shape when adoption proceeds; the executor side is shipped and stable. Posting per the RDR-009 P3 commitment to keep this issue current.

[Hellblazer]

Contract update — v4 (RDR-010): optional harvest request field (additive, response unchanged)

RDR-010 (executor value-harvest) is implemented in qwen-coprocessor-stack. It adds one optional request field to qwen_dispatch; the response shape is unchanged ({artifacts: Artifact[]}, the same four-kind union).

harvest?: "patch" | "value" | "both"   # default "patch"

• "patch" (default) — the source git-diff. Coding runs are byte-identical to v3 — no migration.
• "value" — the dispatched leaf's structured finalMessage surfaced as a single {kind:"value"} artifact (for non-code leaves, e.g. a planner returning JSON).
• "both" — git-diff patch + value.

No response-shape change, so nothing to migrate on the nexus side; a plan that wants a leaf's structured output sets harvest: "value" and reads $stepN.artifacts[?kind=='value'].value | [0]. Sources (qwen-coprocessor-stack): docs/contracts/qwen-dispatch-operator-contract.md (v4) + docs/contracts/fixtures/qwen-dispatch-shapes.json. Posting per the RDR-010 P2 commitment to keep this issue current; additive-only, not a merge gate for nexus.

[Hellblazer]

Orchestrator-side producer contract for the PUSH kinds (entity / tier) — RDR-011

Companion to the executor contract already linked here. The four-kind Artifact union has had producers for patch (RDR-008/009) and value (RDR-010, a dispatched leaf's finalMessage). The remaining two — entity and tier — are orchestrator-produced, not executor-produced: a single one-shot qwen_dispatch returns one leaf's artifacts and structurally cannot accumulate the cross-call, host-side-effect emissions these represent.

We've published the orchestrator-side obligations as a normative, single-actor contract so nexus can adopt the PUSH spine against a spec rather than inferring it:

docs/contracts/harvest-producer-contract.md (qwen-coprocessor-stack), summary:

• Emit-at-side-effect (P1) — the spine emits an entity/tier at the instant it mints a bead/link/rdr or writes a tier; never by post-hoc log scraping (lossy).
• Append-ordered log, not a set (P2) — a workflow ledger is the per-step Artifact[] concatenated in side-effect order; the same target may repeat. Matches the acceptHarvester seam (verbatim, no dedup). Dedup is consumer-side (C-1).
• Identity encoding (P4) — entity{bead}.id = bead id; entity{rdr}.id = RDR-NNN; a catalog link is an edge, so entity{link}.id = composite key "<from>|<type>|<to>" (5-field span form "<from>|<type>|<to>|<from_span>|<to_span>", absent span = empty string; | forbidden in tumbler/link-type). tier.key per-tier: T1 = entry_id, T2 = "project/title", T3 = "collection/doc_id" (/ forbidden inside the components).
• entity.op / tier-upsert asymmetry (P5) — entity carries op:"created"|"updated"; tier has none and is an upsert keyed by (tier,key), latest-wins as a consumer rule (C-2) — a producer still emits every write.
• Failure / concurrency — best-effort, append-only, no retraction on later failure (F1); link endpoints may dangle, consumer handles (F2); parallel-branch interleaving is implementation-defined (F3).
• Composition — the executor emits only patch/value and will not produce entity/tier. An orchestrator MAY promote a leaf's {kind:"value"} into an entity/tier in its own code (orchestrator logic, not executor behavior).

Identity conventions (P4) were verified against the live nexus/conexus identifier surface (bead ids, RDR ids, catalog link edges, T1/T2/T3 keys) — the locked id:string/key:string shapes hold every real identifier with no union change.

This is design-only on our side and commits the executor to nothing; adoption is nexus's call. Happy to adjust the encoding/semantics if they don't fit the plan_run ledger.