@hunter-harness/workflow-harness 0.2.5 → 0.2.6

package/harness/bundles/general/codex/scripts/harness_archive.py

@@ -622,13 +622,16 @@ def _ledger_unit_tests(ledger: dict[str, Any] | None) -> dict[str, Any]:
     status = str(unit.get("status") or "").upper()
     evidence = unit.get("evidence") or {}
     if isinstance(evidence, dict):
-        run = evidence.get("run", unit.get("run", 0))
+        run = evidence.get(
+            "run",
+            evidence.get("testsRun", unit.get("run", unit.get("testsRun", 0))),
+        )
         failures = evidence.get("failures", unit.get("failures", 0))
         errors = evidence.get("errors", unit.get("errors", 0))
         skipped = evidence.get("skipped", unit.get("skipped", 0))
         pass_rate = evidence.get("passRate") or unit.get("passRate")
     else:
-        run = unit.get("run", 0)
+        run = unit.get("run", unit.get("testsRun", 0))
         failures = unit.get("failures", 0)
         errors = unit.get("errors", 0)
         skipped = unit.get("skipped", 0)
@@ -886,16 +889,21 @@ def _durations_from_event_phases(event_summary: dict[str, Any]) -> dict[str, Any
         minutes = round((dur or 0) / 60000, 2) if dur is not None else 0
         if dur:
             total_ms += int(dur)
-        stages.append(
-            {
-                "stage": str(name),
-                "skill": f"harness-{name}",
-                "startedAt": info.get("started_at") or NOT_AVAILABLE,
-                "endedAt": info.get("ended_at") or NOT_AVAILABLE,
-                "minutes": minutes,
-                "result": "OK",
-            }
-        )
+        attempts = info.get("attempts") if isinstance(info.get("attempts"), list) else []
+        result = str(info.get("status") or "UNKNOWN").upper()
+        if result in {"PASS", "PASSED", "SUCCESS"}:
+            result = "OK"
+        elif result in {"FAILED", "ERROR"}:
+            result = "FAIL"
+        stages.append({
+            "stage": str(name),
+            "skill": f"harness-{name}",
+            "startedAt": info.get("started_at") or NOT_AVAILABLE,
+            "endedAt": info.get("ended_at") or NOT_AVAILABLE,
+            "minutes": minutes,
+            "result": result,
+            "attempts": attempts,
+        })
     total_min = round(total_ms / 60000, 2)
     return {
         "totalLabel": f"约 {int(round(total_min))} 分",
@@ -917,11 +925,31 @@ def _stage_status_from_sources(
         "submit": "OK",
         "archive": "OK",
     }
+    for event in events:
+        if event.get("type") != "phase.end":
+            continue
+        phase = str(event.get("phase") or "").lower()
+        raw = str(event.get("status") or "").upper()
+        if phase not in status or not raw:
+            continue
+        if raw in {"PASS", "PASSED", "SUCCESS"}:
+            raw = "OK"
+        elif raw in {"FAILED", "ERROR"}:
+            raw = "FAIL"
+        elif raw in {"SKIP", "SKIPPED"}:
+            raw = "USER_SKIPPED"
+        status[phase] = raw
     # Issues in events can downgrade
     for e in events:
         if e.get("type") != "issue":
             continue
         sev = str(e.get("severity") or "").lower()
+        issue_text = " ".join(str(e.get(key) or "") for key in ("message", "note", "code")).lower()
+        if not sev:
+            if any(token in issue_text for token in ("fail", "error", "blocked", "失败", "阻塞")):
+                sev = "error"
+            elif any(token in issue_text for token in ("warn", "skip", "风险", "警告")):
+                sev = "warn"
         phase = str(e.get("phase") or "").lower()
         if phase in status and sev in {"error", "fail", "failed", "critical"}:
             status[phase] = "FAIL"
@@ -930,14 +958,19 @@ def _stage_status_from_sources(
 
     api = _ledger_api_tests(ledger)
     db = _ledger_db_compat(ledger)
-    if api.get("status") == "USER_SKIPPED":
+    api_status = str(api.get("status") or "").upper()
+    if api_status in {"FAIL", "FAILED", "ERROR"} or int(api.get("failed") or 0) > 0:
+        status["test"] = "FAIL"
+    elif api_status in {"BLOCKED", "BLOCKED_BY_ENV", "BLOCKED_BY_DBA"}:
+        status["test"] = api_status
+    elif api_status == "USER_SKIPPED":
         status["test"] = "USER_SKIPPED"
     elif db == "BLOCKED_BY_DBA":
         status["test"] = "BLOCKED_BY_DBA"
     elif api.get("status") == "NOT_RUN" and not find_test_reports(change_dir):
         unit = _ledger_unit_tests(ledger)
         if unit.get("source") == "not-run" and unit.get("run", 0) == 0:
-            status["test"] = "USER_SKIPPED"
+            status["test"] = "NOT_RUN"
 
     if not find_review_reports(change_dir):
         log_text = load_execution_log(change_dir)
@@ -954,8 +987,6 @@ def _compute_final_status(
     api = verification.get("apiTests") or {}
     db = str(verification.get("dbCompatibility") or "")
     api_status = str(api.get("status") or "")
-    if api_status == "USER_SKIPPED" or db == "BLOCKED_BY_DBA":
-        return "CONDITIONAL_OK"
     for v in stage_status.values():
         if v == "FAIL":
             return "FAIL"
@@ -964,8 +995,14 @@ def _compute_final_status(
         return "FAIL"
     if int(api.get("failed") or 0) > 0:
         return "FAIL"
+    conditional = {
+        "USER_SKIPPED", "BLOCKED", "BLOCKED_BY_ENV", "BLOCKED_BY_DBA",
+        "NOT_RUN", "PARTIAL",
+    }
+    if api_status in conditional or db in conditional:
+        return "CONDITIONAL_OK"
     for v in stage_status.values():
-        if v in {"WARN", "PARTIAL", "USER_SKIPPED", "BLOCKED_BY_DBA"}:
+        if v in {"WARN", *conditional}:
             return "WARN" if v == "WARN" else "CONDITIONAL_OK"
     return "OK"
 
@@ -984,6 +1021,8 @@ def _changed_files_from_git(
     changed: list[dict[str, Any]] = []
     if not base or not head:
         return diff_stat, changed
+    # The ledger bounds the complete task.  Using only ``head^..head`` would
+    # silently omit earlier checkpoint commits from the same change.
     rng = f"{base}..{head}"
     code, out, _ = git_run(project, "diff", "--numstat", rng)
     if code != 0 or not out:
@@ -1040,6 +1079,97 @@ def _review_summary(change_dir: Path, existing: dict[str, Any] | None) -> dict[s
     return base
 
 
+def _final_commit_from_sources(
+    ledger: dict[str, Any] | None,
+    events: list[dict[str, Any]],
+    existing: dict[str, Any] | None,
+    project: Path,
+) -> str:
+    if ledger:
+        for key in (
+            "mergeFinalHash", "finalCommit", "finalHash", "changeCommit", "headCommit",
+        ):
+            value = str(ledger.get(key) or "").strip()
+            if value:
+                return value
+    commit_pattern = re.compile(r"\b[0-9a-f]{7,40}\b", re.IGNORECASE)
+    for event in reversed(events):
+        if str(event.get("phase") or "").lower() not in {"submit", "merge", "archive"}:
+            continue
+        text = " ".join(str(event.get(key) or "") for key in ("note", "message", "command"))
+        match = commit_pattern.search(text)
+        if match:
+            return match.group(0)
+    if existing and existing.get("finalCommit"):
+        return str(existing["finalCommit"])
+    code, head, _ = git_run(project, "rev-parse", "HEAD")
+    return head if code == 0 and head else ""
+
+
+def _business_goal_from_sources(change_dir: Path, events: list[dict[str, Any]]) -> str:
+    plans_root = change_dir / "plans"
+    primary = sorted(plans_root.glob("*-plan.md"))
+    secondary = [
+        path for path in sorted(plans_root.glob("*.md"))
+        if path not in primary
+        and "implementation-detail" not in path.name
+        and "test-scenarios" not in path.name
+    ]
+    for plan in [*primary, *secondary]:
+        try:
+            text = plan.read_text(encoding="utf-8-sig")
+        except OSError:
+            continue
+        body = re.sub(r"\A---\s*\n.*?\n---\s*\n", "", text, count=1, flags=re.DOTALL)
+        goal = re.search(r"(?im)^\s*(?:goal|目标|业务目标|需求)\s*[:：]\s*(.+)$", body)
+        if goal:
+            return goal.group(1).strip()
+        scope = re.search(r"(?im)^\s*>?\s*(?:变更范围|目标)\s*[:：]\s*(.+)$", body)
+        if scope:
+            return scope.group(1).strip()
+        first_task = re.search(r"(?m)^\s*\|\s*1\s*\|\s*([^|]+?)\s*\|", body)
+        if first_task:
+            return first_task.group(1).strip()
+        for line in body.splitlines():
+            clean = line.strip().lstrip("#").strip()
+            if clean and not clean.startswith(("---", ">", "|")) and len(clean) > 8:
+                return clean
+    for event in events:
+        if event.get("type") == "decision":
+            value = str(event.get("decision") or event.get("note") or "").strip()
+            if value:
+                return re.sub(r"^(?:需求收敛|目标)\s*[:：]\s*", "", value)
+    return ""
+
+
+def _timeline_from_events(event_summary: dict[str, Any], events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    timeline: list[dict[str, Any]] = []
+    for phase, info in (event_summary.get("phases") or {}).items():
+        attempts = info.get("attempts") if isinstance(info.get("attempts"), list) else []
+        for attempt in attempts:
+            timeline.append({
+                "phase": phase,
+                "attempt": attempt.get("attempt"),
+                "startedAt": attempt.get("started_at"),
+                "endedAt": attempt.get("ended_at"),
+                "durationMs": attempt.get("duration_ms"),
+                "status": attempt.get("status") or "UNKNOWN",
+                "executorTool": attempt.get("executor_tool"),
+                "executorAgent": attempt.get("executor_agent"),
+                "handoffFromTool": attempt.get("handoff_from_tool"),
+            })
+    for event in events:
+        if event.get("type") not in {"decision", "issue"}:
+            continue
+        timeline.append({
+            "phase": event.get("phase"),
+            "timestamp": event.get("timestamp"),
+            "type": event.get("type"),
+            "summary": event.get("decision") or event.get("message") or event.get("note") or "",
+        })
+    return timeline
+
+
 def collect_summary_data(
     change_dir: Path,
     *,
@@ -1118,18 +1248,14 @@ def collect_summary_data(
         if existing and existing.get("businessGoal"):
             data["businessGoal"] = existing["businessGoal"]
         else:
-            data["businessGoal"] = NOT_AVAILABLE if for_replay else ""
+            inferred_goal = _business_goal_from_sources(change_dir, events)
+            data["businessGoal"] = inferred_goal or (NOT_AVAILABLE if for_replay else "")
 
     # commits
     project = find_project_root(change_dir)
     if not data.get("finalCommit") or str(data.get("finalCommit")).startswith("<"):
-        code, head, _ = git_run(project, "rev-parse", "HEAD")
-        if code == 0 and head:
-            data["finalCommit"] = head
-        elif existing and existing.get("finalCommit"):
-            data["finalCommit"] = existing["finalCommit"]
-        else:
-            data["finalCommit"] = NOT_AVAILABLE if for_replay else ""
+        final_commit = _final_commit_from_sources(ledger, events, existing, project)
+        data["finalCommit"] = final_commit or (NOT_AVAILABLE if for_replay else "")
 
     if not data.get("baseCommit") or str(data.get("baseCommit")).startswith("<"):
         if ledger and ledger.get("baseCommit"):
@@ -1235,18 +1361,43 @@ def collect_summary_data(
     if not isinstance(data.get("artifacts"), list):
         data["artifacts"] = []
     if not for_replay:
-        # Keep empty placeholder for build artifacts; event artifacts go to reportPipeline
-        pass
+        data["artifacts"] = _artifacts_from_events(events)
 
     data["reviewSummary"] = _review_summary(change_dir, existing if for_replay else None)
-    data.setdefault("timeline", [])
+    if not for_replay:
+        data["timeline"] = _timeline_from_events(event_summary, events)
+    else:
+        data.setdefault("timeline", [])
     data.setdefault("uncommittedTestEvidence", [])
 
-    # Model-owned fields: leave empty placeholders on finalize; preserve on replay
+    # Derive risks/actions from evidence. These fields are facts, not model prose.
     if not for_replay:
-        data["maintenanceNotes"] = []
-        data["knownRisks"] = []
+        data["maintenanceNotes"] = [
+            str(event.get("note") or event.get("message") or "")
+            for event in events
+            if event.get("type") == "decision" and (event.get("note") or event.get("message"))
+        ]
+        data["knownRisks"] = [
+            {
+                "phase": event.get("phase"),
+                "severity": event.get("severity") or "unknown",
+                "message": event.get("message") or event.get("note") or event.get("code") or "",
+            }
+            for event in events
+            if event.get("type") == "issue"
+            and not (
+                event.get("phase") == "archive"
+                and event.get("code") == "missing-command"
+            )
+        ]
         data["manualActions"] = []
+        for name, value in (data.get("stageStatus") or {}).items():
+            if value in {"BLOCKED", "BLOCKED_BY_ENV", "BLOCKED_BY_DBA", "NOT_RUN", "USER_SKIPPED"}:
+                data["manualActions"].append({
+                    "stage": name,
+                    "status": value,
+                    "action": "补充或确认该阶段的真实验证证据",
+                })
     else:
         data.setdefault("maintenanceNotes", [])
         data.setdefault("knownRisks", [])
@@ -1978,6 +2129,7 @@ def cmd_finalize(
                 _restore_target,
                 phase="archive",
                 type_="phase.end",
+                status="FAIL",
                 note="finalize aborted; render failed; original preserved",
             )
         except OSError:
@@ -2117,6 +2269,7 @@ def cmd_finalize(
                     _safe_append_restored,
                     phase="archive",
                     type_="phase.end",
+                    status="FAIL",
                     note="finalize aborted; original preserved",
                 )
             except OSError:
@@ -2168,7 +2321,12 @@ def cmd_finalize(
     if service_result.get("warning"):
         warnings.append(str(service_result["warning"]))
 
-    _safe_append(phase="archive", type_="phase.end", note="finalize complete")
+    _safe_append(
+        phase="archive",
+        type_="phase.end",
+        status="WARN" if warnings else "OK",
+        note="finalize complete",
+    )
 
     payload["ok"] = True
     payload["warnings"] = warnings

package/harness/bundles/general/codex/scripts/harness_events.py

@@ -2,7 +2,7 @@
 """Harness events.ndjson writer and execution-log renderer (D2).
 
 Subcommands:
-  append  — append one schema_version 2 event, then auto-render execution-log.md
+  append  — append one schema_version 3 event, then auto-render execution-log.md
   render  — full re-render of logs/execution-log.md from events.ndjson
   summary — phase durations, event counts, and issue list (JSON)
 
@@ -42,7 +42,7 @@ EVENT_TYPES = frozenset(
     }
 )
 
-SCHEMA_VERSION = 2
+SCHEMA_VERSION = 3
 HEADER_LINE = (
     "本文件由 harness_events.py 自动渲染，请勿手工编辑；事实源为 events.ndjson"
 )
@@ -62,6 +62,13 @@ OPTIONAL_FIELDS = (
     "message",
     "decision",
     "reason",
+    "run_id",
+    "attempt",
+    "executor_tool",
+    "executor_agent",
+    "executor_model",
+    "handoff_from_tool",
+    "handoff_reason",
 )
 
 
@@ -120,7 +127,7 @@ def duration_ms_between(start: Any, end: Any) -> int | None:
 
 
 def normalize_event(raw: dict[str, Any]) -> dict[str, Any]:
-    """Normalize schema_version 1/2 events for rendering and summary."""
+    """Normalize schema_version 1/2/3 events for rendering and summary."""
     event = dict(raw)
     version = event.get("schema_version", 1)
     try:
@@ -273,6 +280,15 @@ def build_event(args: argparse.Namespace, existing: list[dict[str, Any]]) -> dic
         if value is None:
             continue
         event[field] = value
+    environment_defaults = {
+        "run_id": "HUNTER_HARNESS_RUN_ID",
+        "executor_tool": "HUNTER_HARNESS_TOOL",
+        "executor_agent": "HUNTER_HARNESS_AGENT",
+        "executor_model": "HUNTER_HARNESS_MODEL",
+    }
+    for field, env_name in environment_defaults.items():
+        if field not in event and os.environ.get(env_name):
+            event[field] = os.environ[env_name]
     if "note" not in event:
         event["note"] = ""
     return event
@@ -333,6 +349,46 @@ def group_events_by_phase(events: list[dict[str, Any]]) -> list[tuple[str, list[
     return [(phase, buckets[phase]) for phase in order]
 
 
+def split_phase_attempts(phase_events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Split repeated starts into attempts and flag legacy events written after end."""
+    attempts: list[dict[str, Any]] = []
+    current: dict[str, Any] | None = None
+    next_attempt = 1
+    for event in phase_events:
+        if event.get("type") == "phase.start":
+            if current is not None:
+                current["warnings"].append("new phase.start before prior phase.end")
+                attempts.append(current)
+            raw_attempt = event.get("attempt")
+            attempt = raw_attempt if isinstance(raw_attempt, int) and raw_attempt > 0 else next_attempt
+            next_attempt = max(next_attempt, attempt + 1)
+            current = {"attempt": attempt, "events": [event], "warnings": []}
+            continue
+        if current is None:
+            if attempts:
+                prior_type = attempts[-1]["events"][-1].get("type")
+                attempts[-1]["events"].append(event)
+                if prior_type == "phase.end":
+                    attempts[-1]["warnings"].append("event recorded after phase.end")
+                continue
+            raw_attempt = event.get("attempt")
+            attempt = raw_attempt if isinstance(raw_attempt, int) and raw_attempt > 0 else next_attempt
+            next_attempt = max(next_attempt, attempt + 1)
+            current = {
+                "attempt": attempt,
+                "events": [event],
+                "warnings": ["missing phase.start"],
+            }
+        else:
+            current["events"].append(event)
+        if event.get("type") == "phase.end":
+            attempts.append(current)
+            current = None
+    if current is not None:
+        attempts.append(current)
+    return attempts
+
+
 def phase_start_time(phase_events: list[dict[str, Any]]) -> str:
     for event in phase_events:
         if event.get("type") == "phase.start":
@@ -352,7 +408,9 @@ def phase_duration_ms(phase_events: list[dict[str, Any]]) -> int | None:
         elif etype == "phase.end":
             end_ts = event.get("timestamp")
     if start_ts and end_ts:
-        return duration_ms_between(start_ts, end_ts)
+        stamps = [e.get("timestamp") for e in phase_events if e.get("timestamp")]
+        effective_end = stamps[-1] if stamps else end_ts
+        return duration_ms_between(start_ts, effective_end)
     # Fallback: first to last timestamp in the phase bucket.
     stamps = [e.get("timestamp") for e in phase_events if e.get("timestamp")]
     if len(stamps) >= 2:
@@ -400,7 +458,15 @@ def render_event_line(event: dict[str, Any]) -> list[str]:
     if etype == "phase.start":
         note = str(event.get("note") or "").strip()
         suffix = f" — {note}" if note else ""
-        return [f"- phase.start @ {event.get('timestamp', '')}{suffix}"]
+        lines = [f"- phase.start @ {event.get('timestamp', '')}{suffix}"]
+        tool = str(event.get("executor_tool") or "").strip()
+        agent = str(event.get("executor_agent") or "").strip()
+        handoff = str(event.get("handoff_from_tool") or "").strip()
+        if handoff and tool:
+            lines.append(f"- 工具交接: {handoff} → {tool}")
+        elif tool:
+            lines.append(f"- 执行来源: {tool}" + (f" / {agent}" if agent else ""))
+        return lines
     if etype == "phase.end":
         note = str(event.get("note") or "").strip()
         suffix = f" — {note}" if note else ""
@@ -445,29 +511,34 @@ def render_execution_log(events: list[dict[str, Any]]) -> str:
         return "\n".join(lines)
 
     for phase, phase_events in group_events_by_phase(events):
-        start = phase_start_time(phase_events) or "—"
-        duration = phase_duration_ms(phase_events)
-        lines.append(f"## {phase} — {start}")
-        lines.append("")
-        if duration is not None:
-            lines.append(f"- 阶段耗时: {format_duration(duration)}")
-        # Collapse consecutive commands into one table.
-        buffer: list[dict[str, Any]] = []
-
-        def flush_commands() -> None:
-            nonlocal buffer
-            if buffer:
-                lines.extend(render_command_block(buffer))
-                buffer = []
-
-        for event in phase_events:
-            if event.get("type") == "command":
-                buffer.append(event)
-                continue
+        attempts = split_phase_attempts(phase_events)
+        for attempt_record in attempts:
+            attempt_events = attempt_record["events"]
+            start = phase_start_time(attempt_events) or "—"
+            duration = phase_duration_ms(attempt_events)
+            label = f"{phase}（尝试 {attempt_record['attempt']}）" if len(attempts) > 1 else phase
+            lines.append(f"## {label} — {start}")
+            lines.append("")
+            if duration is not None:
+                lines.append(f"- 阶段耗时: {format_duration(duration)}")
+            for warning in attempt_record["warnings"]:
+                lines.append(f"- 生命周期警告: {warning}")
+            buffer: list[dict[str, Any]] = []
+
+            def flush_commands() -> None:
+                nonlocal buffer
+                if buffer:
+                    lines.extend(render_command_block(buffer))
+                    buffer = []
+
+            for event in attempt_events:
+                if event.get("type") == "command":
+                    buffer.append(event)
+                    continue
+                flush_commands()
+                lines.extend(render_event_line(event))
             flush_commands()
-            lines.extend(render_event_line(event))
-        flush_commands()
-        lines.append("")
+            lines.append("")
 
     return "\n".join(lines).rstrip() + "\n"
 
@@ -485,21 +556,37 @@ def build_summary(change_dir: Path, events: list[dict[str, Any]]) -> dict[str, A
     issues: list[dict[str, Any]] = []
 
     for phase, phase_events in group_events_by_phase(events):
-        start_ts = None
-        end_ts = None
-        for event in phase_events:
-            if event.get("type") == "phase.start" and start_ts is None:
-                start_ts = event.get("timestamp")
-            elif event.get("type") == "phase.end":
-                end_ts = event.get("timestamp")
-        duration = None
-        if start_ts and end_ts:
-            duration = duration_ms_between(start_ts, end_ts)
+        attempt_records: list[dict[str, Any]] = []
+        for record in split_phase_attempts(phase_events):
+            attempt_events = record["events"]
+            starts = [e for e in attempt_events if e.get("type") == "phase.start"]
+            ends = [e for e in attempt_events if e.get("type") == "phase.end"]
+            start_ts = starts[0].get("timestamp") if starts else None
+            end_ts = ends[-1].get("timestamp") if ends else None
+            provenance = starts[0] if starts else (attempt_events[0] if attempt_events else {})
+            attempt_records.append({
+                "attempt": record["attempt"],
+                "event_count": len(attempt_events),
+                "started_at": start_ts,
+                "ended_at": end_ts,
+                "duration_ms": phase_duration_ms(attempt_events),
+                "status": ends[-1].get("status") if ends else None,
+                "run_id": provenance.get("run_id"),
+                "executor_tool": provenance.get("executor_tool"),
+                "executor_agent": provenance.get("executor_agent"),
+                "handoff_from_tool": provenance.get("handoff_from_tool"),
+                "warnings": record["warnings"],
+            })
+        durations = [a["duration_ms"] for a in attempt_records if a["duration_ms"] is not None]
+        first = attempt_records[0] if attempt_records else {}
+        last = attempt_records[-1] if attempt_records else {}
         phases[phase] = {
             "event_count": len(phase_events),
-            "started_at": start_ts,
-            "ended_at": end_ts,
-            "duration_ms": duration,
+            "started_at": first.get("started_at"),
+            "ended_at": last.get("ended_at"),
+            "duration_ms": sum(durations) if durations else None,
+            "status": last.get("status"),
+            "attempts": attempt_records,
         }
 
     for event in events:
@@ -649,6 +736,13 @@ def build_parser() -> argparse.ArgumentParser:
     p_append.add_argument("--message", default=None)
     p_append.add_argument("--decision", default=None)
     p_append.add_argument("--reason", default=None)
+    p_append.add_argument("--run-id", default=None)
+    p_append.add_argument("--attempt", type=int, default=None)
+    p_append.add_argument("--executor-tool", default=None)
+    p_append.add_argument("--executor-agent", default=None)
+    p_append.add_argument("--executor-model", default=None)
+    p_append.add_argument("--handoff-from-tool", default=None)
+    p_append.add_argument("--handoff-reason", default=None)
     p_append.set_defaults(func=cmd_append)
 
     p_render = sub.add_parser(