prizmkit 1.1.104 → 1.1.106

package/bundled/dev-pipeline/prizmkit_runtime/runners.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import sys
 import time
 from pathlib import Path
 
@@ -15,6 +16,7 @@ from .gitops import (
     branch_ensure_return,
     branch_merge_plan,
     current_branch,
+    default_branch,
     ensure_linked_worktree,
     guarded_worktree_remove,
     materialize_worktree_support_assets,
@@ -24,7 +26,12 @@ from .gitops import (
     worktree_runtime_context,
     worktree_save_wip,
 )
-from .runner_bookkeeping import commit_final_bookkeeping, commit_pre_branch_bookkeeping
+from .runner_bookkeeping import (
+    commit_final_bookkeeping,
+    commit_pre_branch_bookkeeping,
+    commit_task_branch_changes,
+    commit_wip_changes,
+)
 from .runner_classification import classify_session
 from .runner_models import RunnerEnvironment, RunnerFamily, RunnerInvocation, SessionPaths, family_for, parse_invocation
 from .runner_prompts import PromptGenerationResult, generate_prompt
@@ -92,7 +99,10 @@ def _run_pipeline(family: RunnerFamily, invocation: RunnerInvocation, paths) ->
     processed = 0
     details: list[str] = []
     if invocation.item_id:
-        status = _process_item(family, invocation, invocation.item_id, paths, initial_metadata={})
+        try:
+            status = _process_item(family, invocation, invocation.item_id, paths, initial_metadata={})
+        except KeyboardInterrupt:
+            return PipelineRunResult(False, 1, "interrupted", "interrupted", tuple(details))
         return PipelineRunResult(status == "completed", 1, "single_item_done", status, tuple(details))
 
     while True:
@@ -109,10 +119,16 @@ def _run_pipeline(family: RunnerFamily, invocation: RunnerInvocation, paths) ->
         item_id = str(next_result.data.get(f"{family.kind}_id") or next_result.data.get("feature_id") or next_result.data.get("bug_id") or next_result.data.get("refactor_id") or "")
         if not item_id:
             return PipelineRunResult(False, processed, "missing_item_id", details=(marker[:500],))
-        final_status = _process_item(family, invocation, item_id, paths, initial_metadata=next_result.data)
+        try:
+            final_status = _process_item(family, invocation, item_id, paths, initial_metadata=next_result.data)
+        except KeyboardInterrupt:
+            processed += 1
+            details.append(f"{item_id}:interrupted")
+            return PipelineRunResult(False, processed, "interrupted", "interrupted", tuple(details))
         processed += 1
         details.append(f"{item_id}:{final_status}")
         if final_status == "completed":
+            _emit_info(f"Pausing 5s before next {family.kind}...")
             continue
         if final_status == "pending":
             continue
@@ -122,6 +138,167 @@ def _run_pipeline(family: RunnerFamily, invocation: RunnerInvocation, paths) ->
             return PipelineRunResult(False, processed, "item_failed", final_status, tuple(details))
 
 
+_SEPARATOR = "─" * 52
+
+
+def _emit_separator() -> None:
+    print(_SEPARATOR, file=sys.stderr, flush=True)
+
+
+def _emit_info(message: str, *, level: str = "INFO") -> None:
+    timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
+    print(f"{f'[{level}]'.ljust(10)}{timestamp} {message}", file=sys.stderr, flush=True)
+
+
+def _emit_success(message: str) -> None:
+    _emit_info(message, level="SUCCESS")
+
+
+def _emit_warning(message: str) -> None:
+    _emit_info(message, level="WARN")
+
+
+def _family_label(family: RunnerFamily) -> str:
+    return {"feature": "Feature", "bugfix": "Bug", "refactor": "Refactor"}.get(family.kind, family.kind.title())
+
+
+def _max_retries(invocation: RunnerInvocation) -> int:
+    if invocation.max_retries is not None:
+        return max(0, invocation.max_retries)
+    return RunnerEnvironment.from_env().max_retries
+
+
+def _emit_item_header(family: RunnerFamily, invocation: RunnerInvocation, item_id: str, metadata: dict[str, object]) -> None:
+    title = str(metadata.get("title") or metadata.get("description") or "").strip()
+    title_text = f" — {title}" if title else ""
+    retry_count = int(metadata.get("retry_count") or 0)
+    infra_count = int(metadata.get("infra_error_count") or 0)
+    _emit_separator()
+    _emit_info(f"{_family_label(family)}: {item_id}{title_text}")
+    _emit_info(f"Code retry: {retry_count} / {_max_retries(invocation)}")
+    _emit_info(f"Infrastructure retry: {infra_count} / {invocation.max_infra_retries}")
+    _emit_separator()
+
+
+def _is_recovery_side_effect_branch(branch: str, family: RunnerFamily, item_id: str) -> bool:
+    return bool(branch) and branch.startswith(f"{family.branch_prefix}/{item_id}-") and "-recovery-" in branch
+
+
+def _is_current_task_branch(branch: str, family: RunnerFamily, item_id: str) -> bool:
+    if not branch or _is_recovery_side_effect_branch(branch, family, item_id):
+        return False
+    return branch == f"{family.branch_prefix}/{item_id}" or branch.startswith(f"{family.branch_prefix}/{item_id}-")
+
+
+def _resolve_base_branch(project_root: Path, metadata: dict[str, object], active_branch: str, family: RunnerFamily, item_id: str) -> str:
+    recorded = str(metadata.get("base_branch") or "").strip()
+    if recorded:
+        return recorded
+    detected_default = default_branch(project_root)
+    if _is_current_task_branch(active_branch, family, item_id) or _is_recovery_side_effect_branch(active_branch, family, item_id):
+        return detected_default
+    return active_branch or detected_default
+
+
+def _resolve_working_branch(family: RunnerFamily, item_id: str, metadata: dict[str, object], env: RunnerEnvironment, active_branch: str) -> str:
+    recorded = str(metadata.get("active_dev_branch") or "").strip()
+    if recorded and not _is_recovery_side_effect_branch(recorded, family, item_id):
+        return recorded
+    if env.dev_branch and not _is_recovery_side_effect_branch(env.dev_branch, family, item_id):
+        return env.dev_branch
+    if _is_current_task_branch(active_branch, family, item_id):
+        return active_branch
+    return _default_branch_name(family, item_id)
+
+
+def _emit_branch_setup_result(branch_context: BranchContext, result) -> None:
+    results = getattr(result, "results", ()) or ()
+    created = len(results) > 1 and results[1].return_code == 0
+    reused = len(results) > 2 and results[2].return_code == 0 and not created
+    if created:
+        _emit_info(f"Created and checked out branch: {branch_context.working_branch} (from {branch_context.base_branch})")
+    elif reused:
+        _emit_info(f"Reusing branch: {branch_context.working_branch} (from {branch_context.base_branch})")
+    else:
+        _emit_info(f"Dev branch: {branch_context.working_branch}")
+    _emit_info(f"Dev branch: {branch_context.working_branch}")
+
+
+def _emit_git_plan_output(result) -> None:
+    for command_result in getattr(result, "results", ()) or ():
+        for text in (getattr(command_result, "stdout", ""), getattr(command_result, "stderr", "")):
+            stripped = str(text or "").strip()
+            if stripped:
+                print(stripped, file=sys.stderr, flush=True)
+
+
+def _bytes_text(size: int) -> str:
+    if size >= 1024 * 1024:
+        return f"{round(size / (1024 * 1024))}MB"
+    if size >= 1024:
+        return f"{round(size / 1024)}KB"
+    return f"{size}B"
+
+
+def _session_log_summary(session_log: Path) -> tuple[int, str]:
+    try:
+        size = session_log.stat().st_size
+        with session_log.open("r", encoding="utf-8", errors="ignore") as handle:
+            line_count = sum(1 for _ in handle)
+        return line_count, _bytes_text(size)
+    except OSError:
+        return 0, "0B"
+
+
+def _progress_data(path: Path) -> dict[str, object]:
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _emit_prompt_summary(prompt: PromptGenerationResult, session_id: str) -> None:
+    if prompt.pipeline_mode:
+        _emit_info(f"Pipeline mode: {_pipeline_mode_label(prompt.pipeline_mode)}")
+    if prompt.agent_count:
+        critic = "enabled" if prompt.critic_enabled else "disabled"
+        _emit_info(f"Agents: {prompt.agent_count} (critic: {critic})")
+    _emit_info(f"Spawning AI CLI session: {session_id}")
+
+
+def _pipeline_mode_label(mode: str) -> str:
+    labels = {
+        "lite": "lite (Tier 1 — Single Agent)",
+        "standard": "standard (Tier 2 — Orchestrator + Critic/Reviewer)",
+        "full": "full (Tier 3 — Orchestrator + Critic/Reviewer)",
+    }
+    return labels.get(mode, mode)
+
+
+def _emit_session_summary(session_result, session_paths: SessionPaths, classification) -> None:
+    lines, size = _session_log_summary(session_paths.session_log)
+    _emit_info(f"Session log: {lines} lines, {size}")
+    _emit_info(f"exit_code={getattr(session_result, 'exit_code', None)}")
+    _emit_info(f"Session result: {classification.session_status}")
+    progress = _progress_data(session_paths.progress_json)
+    subagent_calls = int(progress.get("subagent_spawn_count") or 0)
+    if subagent_calls:
+        _emit_info(f"Subagent calls detected in session: {subagent_calls}")
+    if classification.session_status == "success":
+        _emit_info("CHECKPOINT: All workflow steps completed")
+
+
+def _emit_update_summary(family: RunnerFamily, item_id: str, update) -> None:
+    if not isinstance(getattr(update, "data", None), dict):
+        return
+    new_status = str(update.data.get("new_status") or "")
+    if family.kind == "feature" and new_status == "completed":
+        _emit_info(f"Propagated completion notes for {item_id} to feature-list.json")
+
+
 def _process_item(
     family: RunnerFamily,
     invocation: RunnerInvocation,
@@ -134,185 +311,306 @@ def _process_item(
     config = load_runtime_config(paths)
     if not config.ai_client.command:
         raise RuntimeError("No supported AI CLI command was found")
-    start = start_item(family, invocation, item_id, paths.project_root)
-    if not start.ok:
-        raise RuntimeError(start.text)
-    commit_pre_branch_bookkeeping(paths.project_root, family, item_id)
 
-    base_branch = str(initial_metadata.get("base_branch") or current_branch(paths.project_root) or "main")
-    branch_name = str(initial_metadata.get("active_dev_branch") or env.dev_branch or _default_branch_name(family, item_id))
+    active_branch = current_branch(paths.project_root)
+    base_branch = _resolve_base_branch(paths.project_root, initial_metadata, active_branch, family, item_id)
+    branch_name = _resolve_working_branch(family, item_id, initial_metadata, env, active_branch)
     branch_context = BranchContext(base_branch, branch_name, paths.project_root)
     worktree_runtime = None
     use_worktree = _use_worktree_for_family(env, family)
     execution_root = paths.project_root
-    if use_worktree:
-        worktree_runtime = worktree_runtime_context(
-            branch_context,
-            WorktreePolicy(
-                use_worktree=True,
-                cleanup_on_success=True,
-                preserve_on_failure=True,
-                worktree_root=paths.state_dir / "worktrees",
-            ),
-        )
-        setup = ensure_linked_worktree(worktree_runtime)
-        if not setup.ok:
-            status = update_item(family, invocation, item_id, "infra_error", "", paths.project_root)
-            return _status_from_update(status)
-        worktree_runtime = setup.runtime or worktree_runtime
-        support_assets = materialize_worktree_support_assets(worktree_runtime)
-        if not support_assets.ok:
-            status = update_item(family, invocation, item_id, "infra_error", "", paths.project_root)
-            return _status_from_update(status)
-        execution_root = worktree_runtime.worktree_path
-    else:
-        branch_result = run_git_plan(paths.project_root, branch_create_plan(branch_context))
-        if not branch_result.ok:
-            status = update_item(family, invocation, item_id, "infra_error", "", paths.project_root)
-            return _status_from_update(status)
-
-    previous_fingerprint = initial_metadata.get("last_progress_fingerprint")
-    previous_no_progress_count = int(initial_metadata.get("no_progress_count") or 0)
-    continuation_pending = bool(initial_metadata.get("continuation_pending"))
-    previous_session_id = str(initial_metadata.get("previous_session_id") or initial_metadata.get("last_context_overflow_session_id") or "")
-    continuation_count = int(initial_metadata.get("continuation_count") or 0)
-    context_overflow_count = int(initial_metadata.get("context_overflow_count") or 0)
 
-    while True:
-        session_id = _session_id(item_id)
-        session_paths = SessionPaths.for_item(family.state_dir, item_id, session_id)
-        continuation = None
-        if continuation_pending:
-            continuation = {
-                "previous_session_id": previous_session_id,
-                "continuation_count": continuation_count,
-                "context_overflow_count": context_overflow_count,
-                "task_type": family.task_type,
-                "active_dev_branch": branch_name,
-                "base_branch": base_branch,
-                "continuation_summary_path": _continuation_summary_path(paths.project_root, family, item_id, None),
-            }
-        prompt = generate_prompt(
-            family,
-            invocation,
-            item_id=item_id,
-            session_id=session_id,
-            run_id="run-python",
-            retry_count=0,
-            session_paths=session_paths,
-            project_root=paths.project_root,
-            execution_root=execution_root,
-            continuation=continuation,
-        )
-        if invocation.dry_run:
-            return "dry_run"
-        stream_json = detect_stream_json_support(config.ai_client.command, config.ai_client.platform).enabled
-        base_head = run_git_command(execution_root, ("rev-parse", "HEAD")).stdout.strip()
-        session_result = AISessionLauncher(
-            AISessionConfig(
-                cli_command=config.ai_client.command,
-                platform=config.ai_client.platform or "codebuddy",
-                model=prompt.model or config.model,
-                prompt_path=prompt.output_path,
-                cwd=execution_root,
-                log_path=session_paths.session_log,
-                progress_path=session_paths.progress_json,
-                heartbeat_path=session_paths.heartbeat_json,
-                effort=config.effort,
-                verbose=env.verbose,
-                live_output=env.live_output,
-                use_stream_json=stream_json,
-                stale_kill_threshold_seconds=env.stale_kill_threshold_seconds,
+    try:
+        if use_worktree:
+            worktree_runtime = worktree_runtime_context(
+                branch_context,
+                WorktreePolicy(
+                    use_worktree=True,
+                    cleanup_on_success=True,
+                    preserve_on_failure=True,
+                    worktree_root=paths.state_dir / "worktrees",
+                ),
             )
-        ).run()
-        classification = classify_session(
-            session_result,
-            project_root=execution_root,
-            base_head=base_head,
-            prompt=prompt,
-            previous_fingerprint=previous_fingerprint,
-            previous_no_progress_count=previous_no_progress_count,
-        )
-        if classification.session_status == "context_overflow":
-            summary_path = _continuation_summary_path(paths.project_root, family, item_id, prompt)
-            update = update_item(
+            setup = ensure_linked_worktree(worktree_runtime)
+            if not setup.ok:
+                return "infra_error"
+            worktree_runtime = setup.runtime or worktree_runtime
+            _emit_info(f"Dev branch: {branch_name}")
+            _emit_info(f"Worktree: {worktree_runtime.worktree_path}")
+            support_assets = materialize_worktree_support_assets(worktree_runtime)
+            if not support_assets.ok:
+                return _record_setup_failure(
+                    family,
+                    invocation,
+                    item_id,
+                    paths.project_root,
+                    worktree_runtime.worktree_path,
+                    base_branch,
+                    branch_name,
+                    worktree_runtime=worktree_runtime,
+                )
+            execution_root = worktree_runtime.worktree_path
+        else:
+            branch_result = run_git_plan(paths.project_root, branch_create_plan(branch_context))
+            _emit_branch_setup_result(branch_context, branch_result)
+            if not branch_result.ok:
+                return "infra_error"
+
+        _emit_item_header(family, invocation, item_id, initial_metadata)
+        status_root = execution_root if use_worktree else paths.project_root
+        status_family = _family_for_execution_root(family, paths.project_root, status_root)
+        status_invocation = _invocation_for_execution_family(invocation, status_family)
+        start = start_item(status_family, status_invocation, item_id, status_root)
+        if not start.ok:
+            raise RuntimeError(start.text)
+        commit_pre_branch_bookkeeping(status_root, status_family, item_id)
+
+        previous_fingerprint = initial_metadata.get("last_progress_fingerprint")
+        previous_no_progress_count = int(initial_metadata.get("no_progress_count") or 0)
+        continuation_pending = bool(initial_metadata.get("continuation_pending"))
+        previous_session_id = str(initial_metadata.get("previous_session_id") or initial_metadata.get("last_context_overflow_session_id") or "")
+        continuation_count = int(initial_metadata.get("continuation_count") or 0)
+        context_overflow_count = int(initial_metadata.get("context_overflow_count") or 0)
+
+        while True:
+            session_id = _session_id(item_id)
+            session_paths = SessionPaths.for_item(family.state_dir, item_id, session_id)
+            continuation = None
+            if continuation_pending:
+                continuation = {
+                    "previous_session_id": previous_session_id,
+                    "continuation_count": continuation_count,
+                    "context_overflow_count": context_overflow_count,
+                    "task_type": family.task_type,
+                    "active_dev_branch": branch_name,
+                    "base_branch": base_branch,
+                    "continuation_summary_path": _continuation_summary_path(execution_root, family, item_id, None),
+                }
+            prompt = generate_prompt(
                 family,
                 invocation,
+                item_id=item_id,
+                session_id=session_id,
+                run_id="run-python",
+                retry_count=0,
+                session_paths=session_paths,
+                project_root=paths.project_root,
+                execution_root=execution_root,
+                continuation=continuation,
+            )
+            if invocation.dry_run:
+                return "dry_run"
+            _emit_prompt_summary(prompt, session_id)
+            stream_json = detect_stream_json_support(config.ai_client.command, config.ai_client.platform).enabled
+            base_head = run_git_command(execution_root, ("rev-parse", "HEAD")).stdout.strip()
+            session_result = AISessionLauncher(
+                AISessionConfig(
+                    cli_command=config.ai_client.command,
+                    platform=config.ai_client.platform or "codebuddy",
+                    model=prompt.model or config.model,
+                    prompt_path=prompt.output_path,
+                    cwd=execution_root,
+                    log_path=session_paths.session_log,
+                    progress_path=session_paths.progress_json,
+                    heartbeat_path=session_paths.heartbeat_json,
+                    effort=config.effort,
+                    verbose=env.verbose,
+                    live_output=env.live_output,
+                    use_stream_json=stream_json,
+                    stale_kill_threshold_seconds=env.stale_kill_threshold_seconds,
+                    live_progress_interval_seconds=env.heartbeat_interval_seconds,
+                    live_banner=False,
+                    suppress_stream_output=True,
+                )
+            ).run()
+            classification = classify_session(
+                session_result,
+                project_root=execution_root,
+                base_head=base_head,
+                prompt=prompt,
+                previous_fingerprint=previous_fingerprint,
+                previous_no_progress_count=previous_no_progress_count,
+            )
+            _emit_session_summary(session_result, session_paths, classification)
+            if classification.session_status == "context_overflow":
+                summary_path = _continuation_summary_path(execution_root, family, item_id, prompt)
+                update = update_item(
+                    status_family,
+                    status_invocation,
+                    item_id,
+                    "context_overflow",
+                    session_id,
+                    status_root,
+                    active_dev_branch=branch_name,
+                    base_branch=base_branch,
+                    last_fatal_error_code=classification.fatal_error_code or "context_overflow",
+                    continuation_summary_path=summary_path,
+                    no_progress_count=classification.no_progress_count,
+                    progress_fingerprint=classification.progress_fingerprint,
+                )
+                if not update.ok:
+                    raise RuntimeError(update.text)
+                _emit_update_summary(family, item_id, update)
+                previous_fingerprint = classification.progress_fingerprint
+                previous_no_progress_count = classification.no_progress_count
+                continuation_pending = True
+                previous_session_id = session_id
+                continuation_count += 1
+                context_overflow_count += 1
+                continue
+
+            final_session_status = classification.session_status
+
+            _write_session_status(
+                session_paths,
+                status=final_session_status,
+                session_id=session_id,
+                task_id=item_id,
+                task_type=family.task_type,
+                base_branch=base_branch,
+                active_dev_branch=branch_name,
+                worktree_path=worktree_runtime.worktree_path if worktree_runtime is not None else None,
+                reason=classification.reason,
+                fatal_error_code=classification.fatal_error_code,
+            )
+
+            update = update_item(
+                status_family,
+                status_invocation,
                 item_id,
-                "context_overflow",
+                final_session_status,
                 session_id,
-                paths.project_root,
+                status_root,
                 active_dev_branch=branch_name,
                 base_branch=base_branch,
-                last_fatal_error_code=classification.fatal_error_code or "context_overflow",
-                continuation_summary_path=summary_path,
+                last_fatal_error_code=classification.fatal_error_code,
                 no_progress_count=classification.no_progress_count,
                 progress_fingerprint=classification.progress_fingerprint,
             )
             if not update.ok:
                 raise RuntimeError(update.text)
-            previous_fingerprint = classification.progress_fingerprint
-            previous_no_progress_count = classification.no_progress_count
-            continuation_pending = True
-            previous_session_id = session_id
-            continuation_count += 1
-            context_overflow_count += 1
-            continue
+            _emit_update_summary(family, item_id, update)
+            new_status = _status_from_update(update)
+            if final_session_status != "success":
+                commit_final_bookkeeping(status_root, status_family, item_id, new_status)
+                _save_failure_wip(execution_root, family, item_id, new_status, worktree_runtime)
+                if use_worktree and worktree_runtime is not None:
+                    guarded_worktree_remove(worktree_runtime, delete_branch=False)
+                else:
+                    branch_ensure_return(paths.project_root, base_branch, branch_name)
+                return new_status
 
-        final_session_status = classification.session_status
-        if use_worktree and worktree_runtime is not None:
-            if final_session_status == "success":
+            commit_final_bookkeeping(status_root, status_family, item_id, new_status)
+            commit_task_branch_changes(execution_root, family, item_id, new_status)
+            if use_worktree and worktree_runtime is not None:
+                _emit_info(f"Merging {branch_name} into {base_branch}...")
                 merge = merge_linked_worktree(worktree_runtime, auto_push=env.auto_push)
+                _emit_git_plan_output(merge)
                 if merge.ok:
                     guarded_worktree_remove(worktree_runtime, delete_branch=True)
-                else:
-                    final_session_status = "merge_conflict"
-                    guarded_worktree_remove(worktree_runtime, delete_branch=False)
+                    _emit_success(f"Merged {branch_name} into {base_branch}")
+                    return new_status
+                final_session_status = "merge_conflict"
             else:
-                worktree_save_wip(worktree_runtime)
-                guarded_worktree_remove(worktree_runtime, delete_branch=False)
-        else:
-            if final_session_status == "success":
+                _emit_info(f"Merging {branch_name} into {base_branch}...")
                 merge = run_git_plan(paths.project_root, branch_merge_plan(branch_context, auto_push=env.auto_push))
-                if not merge.ok:
-                    branch_ensure_return(paths.project_root, base_branch, branch_name)
-                    final_session_status = "merge_conflict"
+                _emit_git_plan_output(merge)
+                if merge.ok:
+                    _emit_success(f"Merged {branch_name} into {base_branch}")
+                    return new_status
+                final_session_status = "merge_conflict"
+
+            _write_session_status(
+                session_paths,
+                status=final_session_status,
+                session_id=session_id,
+                task_id=item_id,
+                task_type=family.task_type,
+                base_branch=base_branch,
+                active_dev_branch=branch_name,
+                worktree_path=worktree_runtime.worktree_path if worktree_runtime is not None else None,
+                reason="merge_conflict",
+                fatal_error_code=classification.fatal_error_code,
+            )
+            update = update_item(
+                status_family,
+                status_invocation,
+                item_id,
+                final_session_status,
+                session_id,
+                status_root,
+                active_dev_branch=branch_name,
+                base_branch=base_branch,
+                last_fatal_error_code=classification.fatal_error_code,
+                no_progress_count=classification.no_progress_count,
+                progress_fingerprint=classification.progress_fingerprint,
+            )
+            if not update.ok:
+                raise RuntimeError(update.text)
+            _emit_update_summary(family, item_id, update)
+            new_status = _status_from_update(update)
+            commit_final_bookkeeping(status_root, status_family, item_id, new_status)
+            _save_failure_wip(execution_root, family, item_id, new_status, worktree_runtime)
+            if use_worktree and worktree_runtime is not None:
+                guarded_worktree_remove(worktree_runtime, delete_branch=False)
             else:
                 branch_ensure_return(paths.project_root, base_branch, branch_name)
+            return new_status
+    except KeyboardInterrupt:
+        _emit_warning(f"Interrupted while processing {item_id}; preserving work and returning to {base_branch}")
+        if use_worktree and worktree_runtime is not None:
+            worktree_save_wip(worktree_runtime)
+            guarded_worktree_remove(worktree_runtime, delete_branch=False)
+        else:
+            branch_ensure_return(paths.project_root, base_branch, branch_name)
+        raise
 
-        _write_session_status(
-            session_paths,
-            status=final_session_status,
-            session_id=session_id,
-            task_id=item_id,
-            task_type=family.task_type,
-            base_branch=base_branch,
-            active_dev_branch=branch_name,
-            worktree_path=worktree_runtime.worktree_path if worktree_runtime is not None else None,
-            reason=classification.reason,
-            fatal_error_code=classification.fatal_error_code,
-        )
 
-        update = update_item(
-            family,
-            invocation,
-            item_id,
-            final_session_status,
-            session_id,
-            paths.project_root,
-            active_dev_branch=branch_name,
-            base_branch=base_branch,
-            last_fatal_error_code=classification.fatal_error_code,
-            no_progress_count=classification.no_progress_count,
-            progress_fingerprint=classification.progress_fingerprint,
-        )
-        if not update.ok:
-            raise RuntimeError(update.text)
-        new_status = _status_from_update(update)
-        commit_final_bookkeeping(paths.project_root, family, item_id, new_status)
-        return new_status
+def _save_failure_wip(execution_root: Path, family: RunnerFamily, item_id: str, status: str, worktree_runtime) -> None:
+    if worktree_runtime is not None:
+        worktree_save_wip(worktree_runtime)
+    else:
+        commit_wip_changes(execution_root, family, item_id, status)
 
 
+def _record_setup_failure(
+    family: RunnerFamily,
+    invocation: RunnerInvocation,
+    item_id: str,
+    project_root: Path,
+    status_root: Path,
+    base_branch: str,
+    branch_name: str,
+    *,
+    worktree_runtime=None,
+) -> str:
+    """Record setup-time infra failures on a task branch when one exists."""
+    if status_root.resolve() == project_root.resolve() and current_branch(project_root) != branch_name:
+        return "infra_error"
+    status_family = _family_for_execution_root(family, project_root, status_root)
+    status_invocation = _invocation_for_execution_family(invocation, status_family)
+    start = start_item(status_family, status_invocation, item_id, status_root)
+    if start.ok:
+        commit_pre_branch_bookkeeping(status_root, status_family, item_id)
+    update = update_item(
+        status_family,
+        status_invocation,
+        item_id,
+        "infra_error",
+        "",
+        status_root,
+        active_dev_branch=branch_name,
+        base_branch=base_branch,
+    )
+    new_status = _status_from_update(update) if update.ok else "infra_error"
+    if update.ok:
+        commit_final_bookkeeping(status_root, status_family, item_id, new_status)
+        _save_failure_wip(status_root, family, item_id, new_status, worktree_runtime)
+    if worktree_runtime is not None:
+        guarded_worktree_remove(worktree_runtime, delete_branch=False)
+    elif current_branch(project_root) == branch_name:
+        branch_ensure_return(project_root, base_branch, branch_name)
+    return new_status
 
 def _test_cli(kind: str, paths) -> CommandResult:
     """Report the AI CLI resolution used by Python runner commands."""
@@ -340,6 +638,52 @@ def _use_worktree_for_family(env: RunnerEnvironment, family: RunnerFamily) -> bo
     return env.use_worktree and family.kind in {"feature", "bugfix"}
 
 
+def _family_for_execution_root(family: RunnerFamily, project_root: Path, execution_root: Path) -> RunnerFamily:
+    """Return family paths rooted in the task execution checkout."""
+    if execution_root.resolve() == project_root.resolve():
+        return family
+    return RunnerFamily(
+        kind=family.kind,
+        id_prefix=family.id_prefix,
+        list_key=family.list_key,
+        list_arg=family.list_arg,
+        item_id_arg=family.item_id_arg,
+        state_dir=_path_in_execution_root(family.state_dir, project_root, execution_root),
+        plan_path=_path_in_execution_root(family.plan_path, project_root, execution_root),
+        updater_script=family.updater_script,
+        prompt_script=family.prompt_script,
+        branch_prefix=family.branch_prefix,
+        artifact_root_name=family.artifact_root_name,
+    )
+
+
+def _invocation_for_execution_family(invocation: RunnerInvocation, family: RunnerFamily) -> RunnerInvocation:
+    return RunnerInvocation(
+        action=invocation.action,
+        list_path=family.plan_path,
+        item_id=invocation.item_id,
+        item_filter=invocation.item_filter,
+        max_retries=invocation.max_retries,
+        max_infra_retries=invocation.max_infra_retries,
+        mode=invocation.mode,
+        critic=invocation.critic,
+        dry_run=invocation.dry_run,
+        clean=invocation.clean,
+        no_reset=invocation.no_reset,
+        resume_phase=invocation.resume_phase,
+        help_requested=invocation.help_requested,
+        unknown_args=invocation.unknown_args,
+        raw_args=invocation.raw_args,
+    )
+
+
+def _path_in_execution_root(path: Path, project_root: Path, execution_root: Path) -> Path:
+    try:
+        return execution_root / path.resolve().relative_to(project_root.resolve())
+    except ValueError:
+        return path
+
+
 def _write_session_status(
     session_paths: SessionPaths,
     *,
@@ -380,8 +724,7 @@ def _status_from_update(update_result) -> str:
 
 
 def _default_branch_name(family: RunnerFamily, item_id: str) -> str:
-    stamp = time.strftime("%Y%m%d%H%M")
-    return f"{family.branch_prefix}/{item_id}-{stamp}"
+    return f"{family.branch_prefix}/{item_id}-{time.strftime('%Y%m%d%H%M%S')}"
 
 
 def _session_id(item_id: str) -> str: