okstra 0.169.0 → 0.169.1

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -45,6 +45,7 @@ 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 (
     InitialPromptMaterializationError,
@@ -60,13 +61,27 @@ from .report_finalize import (
     FinalizeError,
     run_finalize,
 )
+from .worker_audit_ledger import (
+    check_worker_results_audit,
+    parse_worker_result_name,
+)
 from .worker_prompt_body import REPORT_WRITER_WORKER_ID
+from .worker_prompt_headers import (
+    WorkerPromptHeaderError,
+    resolve_errors_log_path,
+)
 from .worker_artifact_paths import audit_sidecar_rel
 from .wrapper_status import read_wrapper_status, status_path_for_prompt
 
 
 MAX_WORKER_ATTEMPTS = 2
 TERMINAL_DISPATCH_STATUSES = {"completed", "timeout", "error", "not-run"}
+# What the error log records for a wrapper the dispatcher timed out, matching
+# the value `team-contract` prescribes for a polling-cap termination.
+_WRAPPER_TIMEOUT_EXIT_CODE = 124
+# The excerpt shares one atomic PIPE_BUF append with the rest of the record, so
+# it is capped far below the writer's own 2048-byte stderr limit.
+_WRAPPER_LOG_TAIL_BYTES = 800
 
 
 @dataclass(frozen=True)
@@ -927,13 +942,22 @@ def _retry_from_record(
     worker_id = _require_string(record, "workerId")
     attempt = int(record.get("attempt", 1))
     job = _job_from_record(plan.project_root, record)
-    _update_dispatch_status(plan.team_state_path, job, attempt, "error", "required worker artifact was not produced")
-    _append_event(plan, "worker-retry-scheduled", {"workerId": worker_id, "attempt": attempt})
+    reason = "required worker artifact was not produced"
+    _update_dispatch_status(plan.team_state_path, job, attempt, "error", reason)
+    # `team-contract` counts the first attempt's failure as a recorded
+    # `cli-failure`; a retry that succeeds settles `completed` and would
+    # otherwise leave no trace that anything had to be re-run.
+    details: dict[str, Any] = {"workerId": worker_id, "attempt": attempt}
+    details["errorLogAppend"] = _record_wrapper_failure(
+        plan, job, attempt, outcome, reason
+    )
+    _append_event(plan, "worker-retry-scheduled", details)
     _spawn_job(plan, job, attempt + 1)
 
 
 def _finish_attempt(plan: DispatchPlan, job: WorkerJob, attempt: int, outcome: WorkerOutcome) -> None:
-    if outcome.returncode == 0 and not outcome.missing_completion_paths and not outcome.timeout:
+    settlement = _settle(plan, job, attempt, outcome)
+    if settlement.completed:
         if job.invocation_id:
             _link_agent_dispatch_result(
                 project_root=plan.project_root,
@@ -965,16 +989,23 @@ def _finish_attempt(plan: DispatchPlan, job: WorkerJob, attempt: int, outcome: W
         _transition_worker_status(
             plan.team_state_path, job.worker_id, "completed", ""
         )
-        _update_dispatch_status(plan.team_state_path, job, attempt, "completed", "")
+        _update_dispatch_status(
+            plan.team_state_path, job, attempt, "completed", settlement.note
+        )
         details = _result_details(job, attempt, outcome)
         details["postProcessing"] = post_process["steps"]
+        if settlement.error_log_append is not None:
+            details["errorLogAppend"] = settlement.error_log_append
         _append_event(plan, "worker-result-collected", details)
         return
-    reason = _failure_reason(outcome)
+    reason = settlement.reason
     status = "timeout" if outcome.timeout else "error"
     _transition_worker_status(plan.team_state_path, job.worker_id, status, reason)
     _update_dispatch_status(plan.team_state_path, job, attempt, status, reason)
-    _append_event(plan, "worker-failed", _failure_details(job, attempt, outcome, reason))
+    details = _failure_details(job, attempt, outcome, reason)
+    if settlement.error_log_append is not None:
+        details["errorLogAppend"] = settlement.error_log_append
+    _append_event(plan, "worker-failed", details)
 
 
 def _finish_record(plan: DispatchPlan, record: Mapping[str, Any], outcome: WorkerOutcome) -> None:
@@ -982,6 +1013,191 @@ def _finish_record(plan: DispatchPlan, record: Mapping[str, Any], outcome: Worke
     _finish_attempt(plan, job, int(record.get("attempt", 1)), outcome)
 
 
+@dataclass(frozen=True)
+class _Settlement:
+    """How one attempt's terminal status was decided."""
+
+    completed: bool
+    reason: str
+    note: str
+    error_log_append: dict[str, Any] | None
+
+
+def _settle(
+    plan: DispatchPlan, job: WorkerJob, attempt: int, outcome: WorkerOutcome
+) -> _Settlement:
+    """Judge an attempt by its artifacts, not by the wrapper's exit code alone.
+
+    A wrapper can die after its worker has already written everything — an
+    observed case is a connection dropped at session teardown, long after the
+    result file and its audit sidecar were on disk. Settling that as `error`
+    discards a complete analysis, and not figuratively: `convergence_engine`
+    admits only dispatches that settled `completed`, so the worker's findings
+    never reach re-verification. The lead's own re-dispatch triggers agree —
+    they name a missing, unparseable, or audit-failing result, never an exit
+    code — but the only signal `team await` gave was the status.
+
+    So a non-zero exit with every completion path present is re-judged by the
+    audit-sidecar contract, the same rules `okstra worker-audit-check` runs. It
+    passes and the dispatch settles `completed`; it fails and the dispatch stays
+    `error` exactly as before. Either way the wrapper's failure is written to the
+    run error log, so a `completed` here is never a swallowed failure.
+    """
+    if outcome.returncode == 0 and not outcome.missing_completion_paths and not outcome.timeout:
+        return _Settlement(True, "", "", None)
+    reason = _failure_reason(outcome)
+    completed = False
+    note = ""
+    if not outcome.timeout and not outcome.missing_completion_paths:
+        audit_failures = _audit_sidecar_failures(job)
+        if audit_failures:
+            reason = (
+                f"{reason}; worker artifacts failed the audit-sidecar "
+                f"contract: {audit_failures[0]}"
+            )
+        else:
+            completed = True
+            note = (
+                f"{reason}, but every completion artifact was written and "
+                f"passed the audit-sidecar contract"
+            )
+    append = _record_wrapper_failure(plan, job, attempt, outcome, note or reason)
+    return _Settlement(completed, "" if completed else reason, note, append)
+
+
+def _audit_sidecar_failures(job: WorkerJob) -> tuple[str, ...]:
+    """This worker's audit-sidecar contract failures, if the check can run.
+
+    The check's arguments come from the result filename rather than the manifest
+    so the scan cannot widen past the file this job produced: `worker-results/`
+    accumulates every run's artifacts, and the `worker=` filter matches the
+    `-worker`-suffixed role, not the bare provider id. A non-canonical name
+    leaves nothing to enforce, and an unverifiable artifact must not be promoted
+    to `completed`, so that reports one failure rather than an empty tuple.
+    """
+    parsed = parse_worker_result_name(job.worker_result_path.name)
+    if parsed is None:
+        return (
+            f"worker result `{job.worker_result_path.name}` is not a canonical "
+            f"`<role>-worker-<task-type>-<seq>.md` name, so the audit-sidecar "
+            f"contract could not be checked",
+        )
+    return tuple(
+        check_worker_results_audit(
+            job.worker_result_path.parent.parent,
+            parsed.task_type,
+            parsed.seq,
+            worker=parsed.worker_role,
+        )
+    )
+
+
+def _record_wrapper_failure(
+    plan: DispatchPlan,
+    job: WorkerJob,
+    attempt: int,
+    outcome: WorkerOutcome,
+    message: str,
+) -> dict[str, Any]:
+    """Write the wrapper's own failure to the run-level error log.
+
+    `okstra-lead-contract` tells Lead the deterministic dispatcher records this
+    and that Lead does not need to re-record it. Nothing did: no code path
+    anywhere called the error-log writer, so every wrapper failure vanished, and
+    with it the `instruction-set/prior-run-errors.md` digest the next run reads
+    and the `/okstra-inspect errors` report. The dispatcher is the only component
+    that holds the exit code, so it is the one that writes.
+
+    Never raises. Logging is bookkeeping around a dispatch that has already
+    settled; letting a rejected or unwritable record throw here would turn a
+    recorded outcome into an unrecorded crash. What went wrong travels back in
+    the lead event instead.
+    """
+    result: dict[str, Any] = {"ok": False, "reason": "", "path": ""}
+    try:
+        out_path = resolve_errors_log_path(
+            plan.project_root,
+            plan.manifest,
+            _load_optional_json(
+                plan.project_root, plan.manifest.get("activeRunContextPath")
+            ),
+        )
+        result["path"] = str(out_path)
+        append_observed(
+            out_path=out_path,
+            task_key=_string_value(plan.manifest.get("taskKey")),
+            phase=_workflow_phase(plan.manifest),
+            agent=_error_log_agent(job.worker_id),
+            agent_role=(
+                "report-writer"
+                if job.worker_id == REPORT_WRITER_WORKER_ID
+                else "worker"
+            ),
+            model=job.model_execution_value,
+            error_type="cli-failure",
+            command=" ".join(job.command),
+            command_kind="wrapper",
+            exit_code=_WRAPPER_TIMEOUT_EXIT_CODE if outcome.timeout else outcome.returncode,
+            duration_ms=_wrapper_duration_ms(outcome),
+            message=f"attempt {attempt}: {message}",
+            stderr_excerpt=_wrapper_log_tail(job),
+            context=None,
+        )
+    except (OSError, ValueError, TypeError, WorkerPromptHeaderError) as exc:
+        result["reason"] = f"{type(exc).__name__}: {exc}"
+        return result
+    result["ok"] = True
+    return result
+
+
+def _error_log_agent(worker_id: str) -> str:
+    """The error log's `--agent` enum value for a worker id.
+
+    The log's own allow-list is the authority on what it accepts; a worker whose
+    name is outside it is reported as such by `append_observed` rather than
+    silently rewritten into some other agent's records.
+    """
+    if worker_id == REPORT_WRITER_WORKER_ID:
+        return REPORT_WRITER_WORKER_ID
+    return f"{worker_id}-worker"
+
+
+def _workflow_phase(manifest: Mapping[str, Any]) -> str:
+    workflow = manifest.get("workflow")
+    if isinstance(workflow, Mapping):
+        return _string_value(workflow.get("currentPhase"))
+    return ""
+
+
+def _wrapper_duration_ms(outcome: WorkerOutcome) -> int | None:
+    if outcome.status_sidecar_path is None:
+        return None
+    status = read_wrapper_status(outcome.status_sidecar_path)
+    if status is None:
+        return None
+    value = status.raw.get("duration_ms")
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _wrapper_log_tail(job: WorkerJob) -> str | None:
+    """The tail of the wrapper transcript, which usually names the real failure.
+
+    The observed case put `API Error: Connection lost mid-response.` in the last
+    two lines and nothing anywhere else; without it the record says only that
+    some process exited 1. Capped well under the writer's own excerpt limit
+    because a whole record must stay inside one atomic `PIPE_BUF` append.
+    """
+    log_path = job.prompt_path.with_suffix(job.prompt_path.suffix + ".log")
+    try:
+        with log_path.open("rb") as handle:
+            handle.seek(0, 2)
+            handle.seek(max(0, handle.tell() - _WRAPPER_LOG_TAIL_BYTES))
+            tail = handle.read()
+    except OSError:
+        return None
+    return tail.decode("utf-8", errors="replace").strip() or None
+
+
 def _post_process_report_writer_result(
     plan: DispatchPlan,
     job: WorkerJob,
@@ -1262,6 +1478,10 @@ def _result_details(job: WorkerJob, attempt: int, outcome: WorkerOutcome) -> dic
         "attempt": attempt,
         "dispatchMode": BACKEND_CLI_WRAPPER if outcome.degraded_from else job.backend,
         "missingCompletionPaths": [],
+        # A collected result can still come from a wrapper that exited non-zero
+        # (`_settle`). The status says the artifacts are good; this says what the
+        # process did, so the trace never loses one fact to the other.
+        "wrapperExitCode": outcome.returncode,
     }
 
 

package/runtime/python/okstra_ctl/error_log_write.py

@@ -0,0 +1,308 @@
+"""Writer core for runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl.
+
+Every error record in a run log is appended through this module. It lives here
+rather than inside `scripts/okstra-error-log.py` because the CLI is no longer the
+only caller: the deterministic dispatcher records a worker wrapper's non-zero
+exit as a `cli-failure` in-process (`dispatch_core`), and the contract sentence
+that says it does is only true while both paths share one writer. The script
+keeps the argparse surface and re-exports these names.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+from pathlib import Path
+
+from .models import provider_ids
+
+STDERR_EXCERPT_MAX_BYTES = 2048
+TRUNCATION_SUFFIX = "...[truncated]"
+PIPE_BUF_BYTES = 4096
+
+ALLOWED_ERROR_TYPES = {"tool-failure", "cli-failure", "contract-violation"}
+# Derived, not listed. The hand-written set had drifted two providers behind the
+# registry: `grok` and `kimi` ship worker definitions and can be dispatched, but
+# their agent names were absent, so every error they reported was rejected at
+# the argument parser — silently, for anyone who did not read the exit code.
+# The registry is where a provider is added, so it is where this follows from.
+ALLOWED_AGENTS = (
+    {f"{provider}-worker" for provider in provider_ids("analyser")}
+    # The report writer is not an analyser and is named without the suffix,
+    # matching `REPORT_WRITER_WORKER_ID`.
+    | {"report-writer"}
+    # Lead identities come from the selected host adapter rather than the
+    # provider registry; `adapters/hosts/*/relay.md` names the value to pass.
+    | {"claude-lead"}
+)
+ALLOWED_AGENT_ROLES = {"lead", "worker", "report-writer"}
+SUPPORTED_SIDECAR_SCHEMA_VERSIONS = {1}
+
+ALLOWED_CAUSES = {
+    "sandbox-denied", "service-unavailable", "auth-failed", "unknown",
+}
+# A `sandbox-denied` claim is only admissible with both probes attached.
+CAUSE_EVIDENCE_FIELDS = ("targetProbe", "controlProbe")
+# Both probes share a record's PIPE_BUF_BYTES budget with stderrExcerpt, so
+# they cannot reuse the 2048 cap that assumes stderrExcerpt owns it alone.
+CAUSE_PROBE_MAX_BYTES = 256
+# Backstop vocabulary: scanned in `message` only — never in stderrExcerpt,
+# where a kernel's real "Operation not permitted" is legitimate content.
+# Deliberately excludes bare "blocked"/"blocks": everyday English that would
+# reject honest records like "test blocked on upstream dependency".
+_BLOCKING_CLAIM_TERMS = (
+    "sandbox", "not permitted", "permission denied", "eperm",
+)
+# The backstop targets *unclassified* blocking claims. A worker that declared
+# a specific cause has already done the honest work — `auth-failed` legitimately
+# reads "permission denied" (MySQL 1045).
+_UNCLASSIFIED_CAUSES = (None, "unknown")
+
+
+def _now_utc():
+    return dt.datetime.now(dt.timezone.utc)
+
+
+def _iso(t):
+    return t.isoformat()
+
+
+def _truncate_utf8(s, limit):
+    """Truncate to `limit` bytes without splitting a multibyte character."""
+    if s is None:
+        return None
+    encoded = s.encode("utf-8")
+    if len(encoded) <= limit:
+        return s
+    cut = encoded[:limit]
+    while cut:
+        try:
+            return cut.decode("utf-8") + TRUNCATION_SUFFIX
+        except UnicodeDecodeError:
+            cut = cut[:-1]
+    return TRUNCATION_SUFFIX
+
+
+def truncate_stderr(s):
+    """Truncate stderr text to STDERR_EXCERPT_MAX_BYTES, multibyte-safe."""
+    return _truncate_utf8(s, STDERR_EXCERPT_MAX_BYTES)
+
+
+def normalize_cause_context(context, *, message):
+    """Validate a record's cause claim and return the normalized context.
+
+    Raises ValueError on three conditions:
+    - `cause` is set to a value outside ALLOWED_CAUSES;
+    - `cause` is 'sandbox-denied' but the two probes are missing or blank —
+      those probes are what distinguish a real denial from an unreachable
+      or auth-gated target, the misdiagnosis this gate exists to stop;
+    - `message` asserts a block in prose while the record left its cause
+      unclassified, which would smuggle the same claim past the gate.
+    """
+    cause = context.get("cause") if isinstance(context, dict) else None
+
+    if cause is not None and cause not in ALLOWED_CAUSES:
+        raise ValueError(
+            f"invalid cause: {cause!r} (allowed: {sorted(ALLOWED_CAUSES)})"
+        )
+
+    if cause == "sandbox-denied":
+        evidence = context.get("causeEvidence")
+        if not isinstance(evidence, dict):
+            raise ValueError(
+                "cause 'sandbox-denied' requires context.causeEvidence with "
+                f"{list(CAUSE_EVIDENCE_FIELDS)}"
+            )
+        normalized_evidence = {}
+        for field in CAUSE_EVIDENCE_FIELDS:
+            value = evidence.get(field)
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(
+                    f"cause 'sandbox-denied' requires a non-empty "
+                    f"context.causeEvidence.{field}: record the command and "
+                    f"its raw output that proves the claim"
+                )
+            normalized_evidence[field] = _truncate_utf8(
+                value, CAUSE_PROBE_MAX_BYTES
+            )
+        return {**context, "causeEvidence": normalized_evidence}
+
+    if message and cause in _UNCLASSIFIED_CAUSES:
+        lowered = message.lower()
+        hit = next((t for t in _BLOCKING_CLAIM_TERMS if t in lowered), None)
+        if hit:
+            raise ValueError(
+                f"message asserts a blocking claim ({hit!r}) without "
+                "context.cause='sandbox-denied' + context.causeEvidence. "
+                "Either attach the two probes, or state the cause you "
+                "actually verified."
+            )
+
+    return context
+
+
+def append_jsonl_line(path, record):
+    """Append a single JSON record as one line to ``path``.
+
+    Atomicity guarantee (POSIX only):
+        With ``O_APPEND`` and a single ``write()`` syscall, the kernel
+        appends the entire payload as one indivisible operation as long as
+        the payload size is at most ``PIPE_BUF`` (4096 bytes on Linux and
+        macOS). Larger payloads may be split across syscalls and interleave
+        with concurrent writers, so this helper rejects them with
+        ``ValueError`` rather than silently losing atomicity.
+
+    The atomicity contract holds only on POSIX filesystems with O_APPEND
+    semantics. Concurrent writers using ``O_TRUNC``, ``unlink``, or
+    non-append modes against the same path break the contract and are
+    out of scope for this helper.
+
+    Caller responsibilities:
+    - Keep records small (this module's stderr excerpt cap of
+      ``STDERR_EXCERPT_MAX_BYTES`` exists to keep records well under
+      ``PIPE_BUF_BYTES``).
+    - Handle ``TypeError`` from ``json.dumps`` for non-serializable values.
+
+    Creates parent directories as needed.
+    """
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    # ensure_ascii=False keeps UTF-8 compact (no \uXXXX escapes).
+    # json.dumps escapes literal newlines inside string values, so the
+    # only unescaped newline is the record separator we append below.
+    line = json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
+    data = line.encode("utf-8")
+    if len(data) > PIPE_BUF_BYTES:
+        raise ValueError(
+            f"record too large for atomic append: {len(data)} bytes > "
+            f"PIPE_BUF ({PIPE_BUF_BYTES})"
+        )
+    # mode 0o644: owner read/write, group/world read-only.
+    fd = os.open(str(p), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
+    try:
+        os.write(fd, data)
+    finally:
+        os.close(fd)
+
+
+def append_observed(
+    *,
+    out_path,
+    task_key,
+    phase,
+    agent,
+    agent_role,
+    model,
+    error_type,
+    command,
+    command_kind,
+    exit_code,
+    duration_ms,
+    message,
+    stderr_excerpt,
+    context,
+    now=None,
+):
+    """Append a lead-observed error event to errors.jsonl."""
+    if error_type not in ALLOWED_ERROR_TYPES:
+        raise ValueError(f"invalid errorType: {error_type!r}")
+    if agent not in ALLOWED_AGENTS:
+        raise ValueError(f"invalid agent: {agent!r}")
+    if agent_role not in ALLOWED_AGENT_ROLES:
+        raise ValueError(f"invalid agentRole: {agent_role!r}")
+    # Runs before append_jsonl_line so a rejected claim leaves no trace in the
+    # log: a written-then-flagged record is still a record someone can cite.
+    context = normalize_cause_context(context, message=message)
+    ts = _iso(now or _now_utc())
+    rec = {
+        "ts": ts,
+        "recordedAt": ts,
+        "taskKey": task_key,
+        "phase": str(phase),
+        "agent": agent,
+        "agentRole": agent_role,
+        "model": model,
+        "source": "lead-observed",
+        "errorType": error_type,
+        "command": command,
+        "commandKind": command_kind,
+        "exitCode": exit_code,
+        "durationMs": duration_ms,
+        "message": message,
+        "stderrExcerpt": truncate_stderr(stderr_excerpt),
+        "context": context,
+    }
+    append_jsonl_line(out_path, rec)
+    return rec
+
+
+def dump_from_worker_sidecar(
+    *,
+    sidecar_path,
+    out_path,
+    task_key,
+    agent,
+    agent_role,
+    model,
+    now=None,
+):
+    """Read worker sidecar errors[] and append each to errors.jsonl with
+    Lead-side metadata filled in. Returns number of records appended.
+
+    Raises ValueError if:
+      - ``agent`` or ``agent_role`` is not in the allow-lists
+      - sidecar ``schemaVersion`` is not in ``SUPPORTED_SIDECAR_SCHEMA_VERSIONS``
+      - any entry's ``errorType`` is not in ``ALLOWED_ERROR_TYPES``
+      - any entry asserts a blocking cause without its required evidence
+
+    Returns 0 (no-op) if the sidecar file does not exist or its
+    ``errors`` list is empty.
+
+    Partial-failure semantics: entries are validated and appended in
+    order. If entry N fails validation, entries 0..N-1 have already
+    been written to ``out_path`` and are NOT rolled back. Callers that
+    require atomicity must validate the sidecar payload before invoking
+    this function.
+    """
+    if agent not in ALLOWED_AGENTS:
+        raise ValueError(f"invalid agent: {agent!r}")
+    if agent_role not in ALLOWED_AGENT_ROLES:
+        raise ValueError(f"invalid agentRole: {agent_role!r}")
+    p = Path(sidecar_path)
+    if not p.exists():
+        return 0
+    payload = json.loads(p.read_text())
+    schema = payload.get("schemaVersion")
+    if schema not in SUPPORTED_SIDECAR_SCHEMA_VERSIONS:
+        raise ValueError(f"unsupported sidecar schemaVersion: {schema!r}")
+    entries = payload.get("errors") or []
+    recorded_at = _iso(now or _now_utc())
+    count = 0
+    for e in entries:
+        et = e.get("errorType")
+        if et not in ALLOWED_ERROR_TYPES:
+            raise ValueError(f"invalid errorType in sidecar: {et!r}")
+        entry_context = normalize_cause_context(
+            e.get("context"), message=e.get("message")
+        )
+        rec = {
+            "ts": e.get("ts"),
+            "recordedAt": recorded_at,
+            "taskKey": task_key,
+            "phase": str(e.get("phase")) if e.get("phase") is not None else None,
+            "agent": agent,
+            "agentRole": agent_role,
+            "model": model,
+            "source": "worker-reported",
+            "errorType": et,
+            "command": e.get("command"),
+            "commandKind": e.get("commandKind"),
+            "exitCode": e.get("exitCode"),
+            "durationMs": e.get("durationMs"),
+            "message": e.get("message"),
+            "stderrExcerpt": truncate_stderr(e.get("stderrExcerpt")),
+            "context": entry_context,
+        }
+        append_jsonl_line(out_path, rec)
+        count += 1
+    return count

package/runtime/python/okstra_ctl/worker_audit_check.py

@@ -12,7 +12,10 @@ import json
 import sys
 from pathlib import Path
 
-from okstra_ctl.worker_audit_ledger import check_worker_results_audit
+from okstra_ctl.worker_audit_ledger import (
+    check_worker_results_audit,
+    worker_result_files,
+)
 
 
 def _parser() -> argparse.ArgumentParser:
@@ -26,7 +29,8 @@ def _parser() -> argparse.ArgumentParser:
     parser.add_argument("--seq", required=True,
                         help="this run's 3-digit seq")
     parser.add_argument("--worker", default=None,
-                        help="check only this worker id (default: every worker)")
+                        help="check only this worker id, with or without the "
+                             "`-worker` suffix (default: every worker)")
     return parser
 
 
@@ -35,8 +39,26 @@ def main(argv: list[str] | None = None) -> int:
     failures = check_worker_results_audit(
         args.run_dir, args.task_type, args.seq, worker=args.worker
     )
-    print(json.dumps({"ok": not failures, "failures": failures},
-                     ensure_ascii=False, indent=2))
+    # A selector that narrows to nothing also produces no failures, so `ok`
+    # alone cannot tell a real pass from a check that judged zero files —
+    # a mistyped `--worker` used to read as a clean bill of health. The count
+    # is what makes the two distinguishable at a glance.
+    inspected = [
+        path.name
+        for path, _role, _seq in worker_result_files(
+            args.run_dir, args.task_type, args.seq, args.worker
+        )
+    ]
+    print(json.dumps(
+        {
+            "ok": not failures,
+            "inspected": len(inspected),
+            "inspectedFiles": inspected,
+            "failures": failures,
+        },
+        ensure_ascii=False,
+        indent=2,
+    ))
     return 2 if failures else 0