HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.
Python agent-apiagent-frameworkagent-harnessai-agentsai-infrastructurecoding-agentconformance-testingdeepseek-harnessharness-engineeringhermesllmopen-protocolopen-sourceopen-standardpi-coding-agentself-hosteduhpunified-apiunified-harness-protocolunified-interface
fix: an incomplete turn says why, and the console stops guessing
richard-epsilla08f324fae44d
diff --git a/gateway/app.py b/gateway/app.pyindex a87bf734..4b25c159 100644--- a/gateway/app.py+++ b/gateway/app.py@@ -2154,6 +2154,10 @@ async def _adopt_orphan_turn(sid: str, org: str, v: dict) -> bool:terminal = ("completed" if st == "done" else "incomplete" if st == "max_turns"else "cancelled" if st == "cancelled" else "incomplete" if st == "timeout"else "failed")+ if st == "max_turns":+ translator.incomplete_reason = "max_steps"+ elif st == "timeout":+ translator.incomplete_reason = "timeout"breakif terminal is None:return False # still running / adoption interrupted — later sweep retries@@ -2330,6 +2334,12 @@ async def _reconcile_response(rid: str, rec: dict) -> dict:if time.time() - _hb_seconds(v) < _RECONCILE_STALE_S:return recsettled = "incomplete"+ # The turn was CUT (replica death, container restart), not capped. Without a reason+ # the console blamed "step or time limit" for a turn that hit neither — a wrong+ # diagnosis shown confidently, live on 2026-08-31 when a deploy restart landed under+ # a running turn.+ rec.setdefault("incomplete_details", None)+ rec["incomplete_details"] = {"reason": "interrupted"}else:hb = _hb_seconds(v)if time.time() - hb >= _RECONCILE_STALE_S: # owner stopped heartbeating → orphaned@@ -4060,6 +4070,12 @@ class _RespTranslator:# is indistinguishable from an honoured one, which is the same reasoning that puts model# substitution in metadata.self.ignored: list[str] = list(ignored or [])+ # WHY an incomplete turn is incomplete. The console showed one banner for every+ # incomplete — "hit its step or time limit" — including turns that hit neither (a+ # replica restart under a live turn settles as incomplete). A wrong diagnosis shown+ # confidently sent an operator debugging a 400-step default that was never reached.+ # "max_steps" | "timeout" | "interrupted"; empty = unknown (old records).+ self.incomplete_reason: str = ""# run metadata (CT-124): the model the caller asked for, and whether the gateway substituted# the harness's authorized default because the request was unavailable for this backend.self.requested_model = ""@@ -4093,7 +4109,9 @@ class _RespTranslator:if self.ignored:meta["ignored_fields"] = self.ignoredreturn {"id": self.resp_id, "object": "response", "created_at": int(self.created_at),- "status": status, "error": self.error, "incomplete_details": None,+ "status": status, "error": self.error,+ "incomplete_details": ({"reason": self.incomplete_reason}+ if status == "incomplete" and self.incomplete_reason else None),"previous_response_id": self.prev, "model": self.model,"output": self.output, "store": self.store, "usage": self.usage,"metadata": meta}@@ -5428,11 +5446,13 @@ async def _resp_execute(translator: _RespTranslator, *, org: str, member: str, sterminal = "completed"elif st == "max_turns":terminal = "incomplete"+ translator.incomplete_reason = "max_steps"elif st in ("cancelled", "timeout"):# user cancel / wall-clock cap end the SESSION's turn — never retry it# on the next connection in the chain (that would re-run the whole task)terminal = "cancelled" if st == "cancelled" else "incomplete"if st == "timeout":+ translator.incomplete_reason = "timeout"rec["tried"].append({"connection": name, "status": st,"error": "turn hit its wall-clock cap"})else:@@ -6457,6 +6477,11 @@ async def _session_turns_data(sid: str, limit: int = 0) -> dict:asst, tools, files = _output_to_turn_fields(rec.get("output") or [])turns.append({"id": rid, "status": rec.get("status"), "user": user_text,"user_files": user_files, "assistant": asst, "tools": tools, "files": files,+ # WHY an incomplete turn is incomplete ("max_steps" | "timeout" |+ # "interrupted"), so the console can say what actually happened instead of+ # one banner for every cause. Absent on records from before the field.+ "incomplete_reason": ((rec.get("incomplete_details") or {}).get("reason")+ or None),"_model": rec.get("model") or "", "_created_at": rec.get("created_at") or 0})# Only the LAST turn can be in-flight, and only it can need reconciliation — both want the# session vertex, so read it ONCE.diff --git a/gateway/tests/test_incomplete_reason.py b/gateway/tests/test_incomplete_reason.pynew file mode 100644index 00000000..6f84e9b5--- /dev/null+++ b/gateway/tests/test_incomplete_reason.py@@ -0,0 +1,37 @@+"""An incomplete turn says WHY, and only when it knows.++One banner for every incomplete — "hit its step or time limit" — misdiagnosed a turn that was+cut by a deploy restart, and sent the operator debugging a 400-step default that was never+reached. The record now carries incomplete_details.reason (max_steps | timeout | interrupted);+absent means unknown, and the console claims nothing specific.+"""+import os+import pathlib+import sys++sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))+os.environ.setdefault("HR_BACKING", "local")+import app as A # noqa: E402+++def _tr(**kw):+ return A._RespTranslator("resp_t", "m", None, True, 0.0, **kw)+++def test_a_capped_turn_names_its_cap():+ tr = _tr()+ tr.incomplete_reason = "max_steps"+ d = tr._response_obj("incomplete")+ assert d["incomplete_details"] == {"reason": "max_steps"}+++def test_an_unknown_cause_stays_null_rather_than_guessing():+ d = _tr()._response_obj("incomplete")+ assert d["incomplete_details"] is None+++def test_a_completed_turn_never_carries_one():+ tr = _tr()+ tr.incomplete_reason = "max_steps" # stale attr must not leak onto a clean finish+ assert _tr()._response_obj("completed")["incomplete_details"] is None+ assert tr._response_obj("completed")["incomplete_details"] is Nonediff --git a/ui/src/app/(app)/workbench/page.tsx b/ui/src/app/(app)/workbench/page.tsxindex de50d24e..54af33df 100644--- a/ui/src/app/(app)/workbench/page.tsx+++ b/ui/src/app/(app)/workbench/page.tsx@@ -104,7 +104,8 @@ function msgsFromTurns(turns: SessionTurn[]): { msgs: Msg[]; running: boolean }: (t.status === 'incomplete' || t.status === 'max_turns' || t.status === 'timeout') ? 'incomplete': (t.status === 'running' || t.status === 'starting' || t.status === 'in_progress') ? 'running' : 'done';if (st === 'running') running = true;- m.push({ role: 'assistant', blocks, files: t.files || [], status: st });+ m.push({ role: 'assistant', blocks, files: t.files || [], status: st,+ incompleteReason: (t as { incomplete_reason?: string }).incomplete_reason || undefined });}return { msgs: m, running };}@@ -783,7 +784,10 @@ interface ToolStep { name: string; args: string; result?: string; callId?: strin// An assistant turn is an ORDERED list of blocks appended as events arrive, so tool activity is// interleaved with prose in real time (not all tools hoisted to the top).type Block = { kind: 'text'; text: string } | { kind: 'tools'; reasoning: string; steps: ToolStep[] };-interface AsstMsg { role: 'assistant'; blocks: Block[]; files: RespFile[]; status: 'running' | 'done' | 'failed' | 'cancelled' | 'incomplete' }+interface AsstMsg { role: 'assistant'; blocks: Block[]; files: RespFile[]; status: 'running' | 'done' | 'failed' | 'cancelled' | 'incomplete';+ /** Why an incomplete turn is incomplete (max_steps | timeout | interrupted) — from the+ * gateway's incomplete_details. Absent on records from before the field existed. */+ incompleteReason?: string }// AGENTS.md / CLAUDE.md are harness-internal instruction files the runner seeds into the workspace// (they surface installed skills to the agent). They are never user-facing outputs, so they must// never render as output file cards, including on older sessions that captured them before the@@ -1239,6 +1243,15 @@ function Conversation({ harnessId, sessionId, target, models, onModel, onRan, on<ChatMessagesmessages={msgs}renderMarkdown={mdRenderer}+ // The default incomplete badge asserted "step or time limit" for EVERY incomplete —+ // including turns that hit neither (a deploy restart under a live turn settles as+ // incomplete). The badge now claims only what is true of all causes; the specific+ // cause, when the record carries one, renders per turn in the footer below.+ statusLabels={{+ failed: '✕ Failed — see the output above for the reason',+ cancelled: '◼ Stopped by you',+ incomplete: '◔ Stopped before finishing — Continue to resume',+ }}userExtras={(m: UserMsg) => (m.attachments && m.attachments.length > 0 ? (<div className="wbx-attach-row">{m.attachments.map((f, j) => <AttachCard key={j} name={f.name} dataUri={f.dataUri} />)}@@ -1246,6 +1259,15 @@ function Conversation({ harnessId, sessionId, target, models, onModel, onRan, on) : null)}assistantFooter={(m: AsstMsg, i: number) => (<>+ {m.status === 'incomplete' && m.incompleteReason && (+ <div className="wbx-incomplete-why">+ {m.incompleteReason === 'max_steps' ? 'It hit its step limit.'+ : m.incompleteReason === 'timeout' ? 'It hit its time limit.'+ : m.incompleteReason === 'interrupted'+ ? 'The turn was interrupted before it finished — for example by a server restart. No limit was hit.'+ : null}+ </div>+ )}{m.files.filter((f) => !isInternalOutput(f.filename)).length > 0 && (<div className="wbx-files">{m.files.filter((f) => !isInternalOutput(f.filename)).map((f, j) => (diff --git a/ui/src/app/hr.css b/ui/src/app/hr.cssindex c1589891..0204d6ab 100644--- a/ui/src/app/hr.css+++ b/ui/src/app/hr.css@@ -956,3 +956,7 @@ body.hr-resizing iframe { pointer-events: none; }.kit-db .mcp-test-row .hr-btn { flex: 1 1 auto; justify-content: center; }}++/* Why an incomplete turn is incomplete — one quiet line under the neutral badge, only when the+ record actually knows the cause. */+.wbx-incomplete-why { font-size: 12.5px; color: var(--mut, #6b7280); margin: 4px 0 0 2px; }