okstra 0.169.1 → 0.170.1

package/runtime/python/okstra_ctl/agent_invocation.py

@@ -18,6 +18,9 @@ from typing import Iterator, Literal, Mapping, get_args
 AgentAudience = Literal[
     "lead",
     "analysis-worker",
+    "discovery-worker",
+    "diagnosis-worker",
+    "planning-worker",
     "implementation-executor",
     "implementation-verifier",
     "acceptance-verifier",
@@ -31,7 +34,36 @@ AgentAudience = Literal[
 ]
 
 _SUPPORTED_AUDIENCES = frozenset(get_args(AgentAudience))
+# The section set IS the duty contract's shape: a duty author adding a role file
+# reads these names, and `_validate_duty_sections` refuses a file that misses one.
+# The check is structural — it proves every required section exists and carries
+# text, NOT that the text is a real contract. A one-line placeholder passes it;
+# what keeps a section substantive is review, and the rule that earns a section a
+# place here at all: a sentence that reads the same in another duty file belongs
+# in `common.md` or nowhere.
+COMMON_DUTY_SECTIONS = (
+    "Assignment fidelity",
+    "Required inputs",
+    "Evidence first",
+    "Authority and scope",
+    "Collaboration and independence",
+    "Instruction precedence",
+    "Conflict handling",
+    "Completion honesty",
+)
+ROLE_DUTY_SECTIONS = (
+    "Responsibility",
+    "Required conduct",
+    "Decision principles",
+    "Authority and boundaries",
+    "Evidence standard",
+    "Collaboration contract",
+    "Completion criteria",
+    "Forbidden conduct",
+    "Blocked-state reporting",
+)
 _SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_DUTY_SECTION_RE = re.compile(r"(?m)^## ([^\n]+)\s*$")
 _TOP_LEVEL_KEYS = {
     "schemaVersion",
     "invocationId",
@@ -213,6 +245,7 @@ def load_common_duty_contract(duty_root: Path) -> DutyContract:
         raise AgentInvocationError(f"invalid common duty frontmatter: {path}")
     if fields["id"] != "common" or fields["kind"] != "common":
         raise AgentInvocationError(f"invalid common duty frontmatter: {path}")
+    _validate_duty_sections(body, COMMON_DUTY_SECTIONS, "common", path)
     return DutyContract(
         id="common",
         version=_parse_version(fields["version"], path),
@@ -902,7 +935,7 @@ def _publish_or_reuse(
     if metadata_exists and not prompt_exists:
         raise _existing_conflict("metadata exists without prompt")
     if prompt_exists and prompt.read_bytes() != materialized.prompt_bytes:
-        _replace_undispatched(request, materialized)
+        _replace_undispatched(request, materialized, _prompt_difference(prompt, materialized))
         return
     if prompt_exists and metadata_exists:
         if metadata.read_bytes() != materialized.metadata_bytes:
@@ -913,8 +946,37 @@ def _publish_or_reuse(
     _publish_exclusive(metadata, materialized.metadata_bytes)
 
 
+def _prompt_difference(prompt: Path, materialized: _MaterializedInvocation) -> str:
+    """What actually differs between the published prompt and this one.
+
+    "existing prompt differs" alone cannot be acted on: it does not say whether
+    the file on disk is a stale sibling, a partially written artifact, or the
+    same prompt built from an edited instruction file — and the evidence is
+    destroyed by the very republish that unblocks the caller. One real
+    investigation ended undecided for exactly this reason. Digests identify the
+    two bodies, and the first differing line points at the edit.
+    """
+    try:
+        existing = prompt.read_bytes()
+    except OSError as exc:
+        return f"existing prompt is unreadable: {exc}"
+    composed = materialized.prompt_bytes
+    detail = (
+        f"existing {_sha256(existing)}, composed {_sha256(composed)}"
+    )
+    existing_lines = existing.decode("utf-8", errors="replace").splitlines()
+    composed_lines = composed.decode("utf-8", errors="replace").splitlines()
+    for index, (left, right) in enumerate(zip(existing_lines, composed_lines), start=1):
+        if left != right:
+            return f"{detail}, first differing line {index}"
+    shorter = min(len(existing_lines), len(composed_lines))
+    return f"{detail}, identical through line {shorter} then one body continues"
+
+
 def _replace_undispatched(
-    request: AgentInvocationRequest, materialized: _MaterializedInvocation
+    request: AgentInvocationRequest,
+    materialized: _MaterializedInvocation,
+    difference: str,
 ) -> None:
     """Rewrite a prompt this invocation id wrote but no dispatch ever used.
 
@@ -930,7 +992,7 @@ def _replace_undispatched(
     agent — puts the prompt back under the original rule.
     """
     if not request.replace_undispatched:
-        raise _existing_conflict("existing prompt differs")
+        raise _existing_conflict(f"existing prompt differs ({difference})")
     dispatched = _recorded_dispatch_ids(request)
     if dispatched:
         raise _existing_conflict(
@@ -1541,6 +1603,7 @@ def _load_role_duty(path: Path) -> DutyContract:
         raise AgentInvocationError(f"unknown duty audience: {audience}")
     if fields["kind"] != "role" or fields["id"] != audience:
         raise AgentInvocationError(f"invalid role duty frontmatter: {path}")
+    _validate_duty_sections(body, ROLE_DUTY_SECTIONS, "role", path)
     return DutyContract(
         id=fields["id"],
         version=_parse_version(fields["version"], path),
@@ -1572,6 +1635,32 @@ def _parse_duty_file(path: Path) -> tuple[dict[str, str], str]:
     return fields, "".join(lines[end + 1 :]).lstrip("\n")
 
 
+def _validate_duty_sections(
+    body: str,
+    required: tuple[str, ...],
+    kind: str,
+    path: Path,
+) -> None:
+    matches = list(_DUTY_SECTION_RE.finditer(body))
+    sections: dict[str, str] = {}
+    for index, match in enumerate(matches):
+        name = match.group(1).strip()
+        if name in sections:
+            raise AgentInvocationError(f"duplicate {kind} duty section {name}: {path}")
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(body)
+        sections[name] = body[match.end() : end].strip()
+    missing = [name for name in required if name not in sections]
+    if missing:
+        raise AgentInvocationError(
+            f"missing {kind} duty sections: {', '.join(missing)}: {path}"
+        )
+    empty = [name for name in required if not sections[name]]
+    if empty:
+        raise AgentInvocationError(
+            f"empty {kind} duty sections: {', '.join(empty)}: {path}"
+        )
+
+
 def _parse_version(value: str, path: Path) -> int:
     try:
         version = int(value)

package/runtime/python/okstra_ctl/agent_prompt_cli.py

@@ -41,6 +41,7 @@ from .dispatch_state import (
     DispatchError,
     link_agent_dispatch_result,
     record_verified_agent_dispatch,
+    reject_agent_dispatch_result,
 )
 
 
@@ -110,6 +111,18 @@ def _parser() -> argparse.ArgumentParser:
     )
     record_dispatch.add_argument("--json", action="store_true")
 
+    reject_result = commands.add_parser(
+        "reject-result",
+        help="mark a linked result rejected so a corrective re-dispatch can "
+             "claim its path",
+    )
+    _common_paths(reject_result)
+    reject_result.add_argument("--run-manifest", required=True)
+    reject_result.add_argument("--dispatch-id", required=True)
+    reject_result.add_argument("--superseded-by", required=True)
+    reject_result.add_argument("--reason", required=True)
+    reject_result.add_argument("--json", action="store_true")
+
     link_result = commands.add_parser("link-result")
     _common_paths(link_result)
     link_result.add_argument("--run-manifest", required=True)
@@ -156,6 +169,9 @@ def main(argv: list[str] | None = None) -> int:
         if args.command == "record-dispatch":
             _record_dispatch(args)
             return 0
+        if args.command == "reject-result":
+            _reject_result(args)
+            return 0
         _link_result(args)
         return 0
     except (
@@ -192,6 +208,20 @@ def _record_dispatch(args: argparse.Namespace) -> None:
     _emit(record, args.json)
 
 
+def _reject_result(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    row = reject_agent_dispatch_result(
+        project_root=project_root,
+        run_manifest_path=_project_input(
+            project_root, args.run_manifest, "run manifest"
+        ),
+        dispatch_id=args.dispatch_id,
+        superseded_by=args.superseded_by,
+        reason=args.reason,
+    )
+    _emit(row, args.json)
+
+
 def _link_result(args: argparse.Namespace) -> None:
     project_root = _project_root(args.project_root)
     link = link_agent_dispatch_result(

package/runtime/python/okstra_ctl/cmux.py

@@ -199,17 +199,23 @@ def plan_worker_placement(
     return _extend_the_shortest_column(columns)
 
 
-def lead_shrink_points(lead: PaneGeometry, *, target_columns: int) -> int:
-    """How far to push the lead's right border, in the points `pane.resize` takes.
+def lead_resize_points(lead: PaneGeometry, *, target_columns: int) -> int:
+    """How far to move the lead's right border, in the points `pane.resize` takes.
+
+    Signed: positive when the lead is too wide and the border comes in, negative
+    when it is too narrow and the border goes out.
+
+    Both directions are needed. A split halves whatever pane it lands on, and
+    the first worker of every round lands on the lead — so a rule that only ever
+    shrinks leaves that half permanent, and the round after it takes half of
+    what is left. Measured on this display: 215 columns becomes 80, then 40,
+    then 20, until neither the lead nor its workers can be read.
 
     The API's `amount` is points, not cells — measured at this pane's own
-    `cell_width_points`, so passing a column count shrinks by an eighth of the
-    intent on a typical display.
+    `cell_width_points`, so passing a column count moves the border by an eighth
+    of the intent on a typical display.
     """
-    surplus = lead.columns - target_columns
-    if surplus <= 0:
-        return 0
-    return surplus * lead.cell_width_points
+    return (lead.columns - target_columns) * lead.cell_width_points
 
 
 def _holds_an_okstra_surface(
@@ -326,7 +332,7 @@ def spawn_worker_surface(
     surface_uuid = _open_worker_surface(workspace, placement, target)
     run_cmux(["rename-tab", "--surface", surface_uuid, "--title", title])
     _exec_worker(surface_uuid, cwd=cwd, command=command)
-    _shrink_lead_pane(workspace)
+    _size_lead_pane(workspace)
     return surface_uuid
 
 
@@ -530,28 +536,39 @@ def _exec_worker(surface_uuid: str, *, cwd: Path, command: Sequence[str]) -> Non
         raise RuntimeError(started.stderr.strip() or "cmux could not start the worker")
 
 
-def _shrink_lead_pane(workspace: str) -> None:
-    """Give the lead's width to the workers by pushing its right border left.
+def _size_lead_pane(workspace: str) -> None:
+    """Put the lead back on its target width, leaving the rest to the workers.
+
+    Which pane carries the request follows from what `pane.resize` does: it
+    moves the named pane's own border in the direction given. The lead can push
+    its right border out — that is `right` on the lead itself — but it cannot
+    pull that border in, because `left` on the leftmost pane finds no adjacent
+    border to move. Narrowing is therefore the right-hand neighbour's request,
+    and widening is the lead's.
 
-    The lead cannot shrink itself: `pane.resize` moves the named pane's border,
-    so asking the leftmost pane to move `left` fails with no adjacent border and
-    `right` widens it. The neighbour on its right carries the request instead.
+    Run after every worker opens rather than once per round: the split that just
+    happened is what knocked the lead off its width, and no other event does.
     """
     panes = list_panes(workspace)
     lead = _lead_pane(panes)
-    amount = lead_shrink_points(lead, target_columns=LEAD_TARGET_COLUMNS)
-    if amount <= 0:
+    offset = lead_resize_points(lead, target_columns=LEAD_TARGET_COLUMNS)
+    if offset == 0:
         return
     neighbours = [pane for pane in panes if pane.x > lead.x]
     if not neighbours:
         return
+    narrowing = offset > 0
     rpc(
         "pane.resize",
         {
             "workspace_id": workspace,
-            "pane_id": min(neighbours, key=lambda pane: pane.x).pane_id,
-            "direction": "left",
-            "amount": amount,
+            "pane_id": (
+                min(neighbours, key=lambda pane: pane.x).pane_id
+                if narrowing
+                else lead.pane_id
+            ),
+            "direction": "left" if narrowing else "right",
+            "amount": abs(offset),
         },
     )
 

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -19,7 +19,9 @@ from .dispatch_state import (
     append_worker_dispatch as _append_worker_dispatch,
     DispatchError,
     WorkerJob,
+    dispatch_completion_paths as _completion_paths,
     dispatch_mode as _dispatch_mode,
+    dispatch_result_path as _result_path_for_worker,
     LIVENESS_AUDIT_HEARTBEAT,
     LIVENESS_WRAPPER_STATUS,
     load_json_object as _load_json_object,
@@ -41,10 +43,6 @@ from .dispatch_state import (
     worker_state as _worker_state,
     worktree_path as _worktree_path,
 )
-from .final_report_paths import (
-    final_report_data_path as _final_report_data_path,
-    final_report_markdown_path as _final_report_markdown_path,
-)
 from .error_log_write import append_observed
 from .lead_events import LeadEvent, append_lead_event
 from .initial_prompt_materialization import (
@@ -55,6 +53,8 @@ from .initial_prompt_materialization import (
     materialize_initial_prompts,
 )
 from .path_hints import hydrate_active_run_context
+from .schema_excerpt import bundle_excerpt_path, excerpt_version_skew
+from .seeding import installed_version
 from .report_finalize import (
     STEP_VALIDATE_RUN,
     FinalizeContext,
@@ -191,7 +191,7 @@ def build_dispatch_plan(
         default_provider_by_worker_id=dict(default_provider_by_worker_id or {}),
     )
     if jobs_file:
-        jobs = _jobs_from_file(project_root, workspace_root, jobs_file, options)
+        jobs = _jobs_from_file(project_root, workspace_root, jobs_file, manifest, options)
     else:
         jobs = _jobs_from_roster(
             project_root,
@@ -204,6 +204,7 @@ def build_dispatch_plan(
             options,
         )
     _validate_dispatch_prompts(manifest, active_context, jobs)
+    _reject_stale_schema_excerpt(project_root, manifest, jobs)
     return DispatchPlan(
         project_root=project_root,
         workspace_root=workspace_root.resolve(),
@@ -705,6 +706,7 @@ def _jobs_from_file(
     project_root: Path,
     workspace_root: Path,
     jobs_file: Path | None,
+    manifest: Mapping[str, Any],
     options: _BuildOptions,
 ) -> list[WorkerJob]:
     if jobs_file is None:
@@ -712,6 +714,7 @@ def _jobs_from_file(
     return _worker_jobs_from_file(
         project_root,
         jobs_file,
+        manifest=manifest,
         backend=options.default_backend,
         idle_timeout_seconds=options.idle_timeout_seconds,
         default_dispatch_kind=options.dispatch_kind,
@@ -958,13 +961,7 @@ def _retry_from_record(
 def _finish_attempt(plan: DispatchPlan, job: WorkerJob, attempt: int, outcome: WorkerOutcome) -> None:
     settlement = _settle(plan, job, attempt, outcome)
     if settlement.completed:
-        if job.invocation_id:
-            _link_agent_dispatch_result(
-                project_root=plan.project_root,
-                run_manifest_path=plan.manifest_path,
-                dispatch_id=f"{job.invocation_id}:attempt-{attempt}",
-                result_path=job.worker_result_path,
-            )
+        result_link = _link_result(plan, job, attempt)
         post_process = _post_process_report_writer_result(plan, job)
         if not post_process["ok"]:
             reason = _require_string(post_process, "reason")
@@ -990,10 +987,15 @@ def _finish_attempt(plan: DispatchPlan, job: WorkerJob, attempt: int, outcome: W
             plan.team_state_path, job.worker_id, "completed", ""
         )
         _update_dispatch_status(
-            plan.team_state_path, job, attempt, "completed", settlement.note
+            plan.team_state_path,
+            job,
+            attempt,
+            "completed",
+            "; ".join(part for part in (settlement.note, result_link["reason"]) if part),
         )
         details = _result_details(job, attempt, outcome)
         details["postProcessing"] = post_process["steps"]
+        details["resultLink"] = result_link
         if settlement.error_log_append is not None:
             details["errorLogAppend"] = settlement.error_log_append
         _append_event(plan, "worker-result-collected", details)
@@ -1008,6 +1010,43 @@ def _finish_attempt(plan: DispatchPlan, job: WorkerJob, attempt: int, outcome: W
     _append_event(plan, "worker-failed", details)
 
 
+def _link_result(
+    plan: DispatchPlan, job: WorkerJob, attempt: int
+) -> dict[str, Any]:
+    """Bind this result to its verified dispatch, reporting rather than raising.
+
+    Linking is bookkeeping around a dispatch that has already settled, and it
+    used to run before any status was written. A refused link — the live case is
+    a corrective re-dispatch claiming a path the first attempt still owns — threw
+    out of `_finish_attempt`, so nothing transitioned, the row stayed `running`,
+    and the exception reached the caller as exit 2. The next `await` re-read the
+    same terminal sidecar, re-settled the same way, and threw at the same line:
+    a worker with complete artifacts wedged the run permanently, and no amount of
+    waiting could clear it.
+
+    So the settle is written either way and the refusal travels back as data. It
+    is not swallowed: the reason lands in the dispatch row and in the lead event,
+    and the post-hoc validators still require every accepted result to carry a
+    link, so an unlinked result fails where an audit failure belongs rather than
+    by stopping the run mid-phase. `agent-prompt reject-result` is the remedy the
+    refusal names.
+    """
+    link: dict[str, Any] = {"ok": True, "reason": ""}
+    if not job.invocation_id:
+        return link
+    try:
+        _link_agent_dispatch_result(
+            project_root=plan.project_root,
+            run_manifest_path=plan.manifest_path,
+            dispatch_id=f"{job.invocation_id}:attempt-{attempt}",
+            result_path=job.worker_result_path,
+        )
+    except (DispatchError, OSError) as exc:
+        link["ok"] = False
+        link["reason"] = f"result link refused: {exc}"
+    return link
+
+
 def _finish_record(plan: DispatchPlan, record: Mapping[str, Any], outcome: WorkerOutcome) -> None:
     job = _job_from_record(plan.project_root, record)
     _finish_attempt(plan, job, int(record.get("attempt", 1)), outcome)
@@ -1626,17 +1665,48 @@ def _provider_for_worker(
     return worker_id
 
 
-def _result_path_for_worker(worker_id: str, result_path: Path, manifest: Mapping[str, Any], project_root: Path) -> Path:
-    if worker_id != REPORT_WRITER_WORKER_ID:
-        return result_path
-    return _final_report_data_path(_resolve_required_path(project_root, manifest, "expectedReportPath"))
 
 
-def _completion_paths(worker_id: str, result_path: Path, manifest: Mapping[str, Any], project_root: Path) -> tuple[Path, ...]:
-    if worker_id != REPORT_WRITER_WORKER_ID:
-        return (result_path,)
-    data_json = _final_report_data_path(_resolve_required_path(project_root, manifest, "expectedReportPath"))
-    return (data_json, _final_report_markdown_path(data_json), result_path)
+def _reject_stale_schema_excerpt(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    jobs: Sequence[WorkerJob],
+) -> None:
+    """Refuse to send the report writer at a schema excerpt from another runtime.
+
+    The bundle's `instruction-set/final-report-schema.json` is cut at prep time
+    and never moves again, while validation always runs against the installed
+    schema. A run long enough to straddle a runtime upgrade therefore has the
+    author writing to one contract and the validator reading another — and the
+    only thing that noticed was the renderer, in Phase 6, after the worker had
+    authored the whole report. The two versions are comparable the moment the
+    dispatch is built, and the remedy is the same either way, so it belongs here.
+
+    Only the report writer is stopped: it is the only worker that authors against
+    the excerpt. Re-running bundle prep re-cuts it from the installed schema.
+    """
+    writer = next(
+        (job for job in jobs if job.worker_id == REPORT_WRITER_WORKER_ID), None
+    )
+    if writer is None:
+        return
+    expected = _string_value(manifest.get("expectedReportPath"))
+    if not expected:
+        return
+    excerpt_path = bundle_excerpt_path(_resolve_project_path(project_root, expected))
+    if excerpt_path is None:
+        return
+    installed = installed_version()
+    cut_from = excerpt_version_skew(excerpt_path, installed)
+    if not cut_from:
+        return
+    raise DispatchError(
+        f"the bundle's schema excerpt ({excerpt_path}) was cut from okstra "
+        f"{cut_from} but this runtime is {installed}. The report writer authors "
+        f"against that excerpt and validation runs against the installed schema, "
+        f"so dispatching now spends a full authoring pass on the wrong contract. "
+        f"Re-prepare the task bundle to re-cut the excerpt, then dispatch again."
+    )
 
 
 def _run_dir(plan: DispatchPlan) -> Path: