prizmkit 1.1.106 → 1.1.108

package/bundled/dev-pipeline/tests/test_unified_cli.py

@@ -171,12 +171,12 @@ def test_runtime_config_matches_canonical_ai_cli_precedence(tmp_path):
     pipeline = project / ".prizmkit" / "dev-pipeline"
     pipeline.mkdir(parents=True)
     prizmkit_dir = project / ".prizmkit"
-    (prizmkit_dir / "config.json").write_text(json.dumps({"ai_cli": "config-cbc", "platform": "claude"}), encoding="utf-8")
+    (prizmkit_dir / "config.json").write_text(json.dumps({"ai_cli": "cbc", "platform": "claude"}), encoding="utf-8")
     (prizmkit_dir / "manifest.json").write_text(json.dumps({"platform": "codex"}), encoding="utf-8")
     paths = resolve_runtime_paths(pipeline_root=pipeline)
 
     config_cli = load_runtime_config(paths, env={"PATH": ""}).ai_client
-    assert config_cli.command == "config-cbc"
+    assert config_cli.command == "cbc"
     assert config_cli.platform == "codebuddy"
     assert config_cli.source == "prizmkit-config:ai_cli"
 
@@ -195,6 +195,73 @@ def test_runtime_config_matches_canonical_ai_cli_precedence(tmp_path):
     assert legacy_alias.source == "environment:CODEBUDDY_CLI"
 
 
+def test_runtime_config_resolves_custom_ai_cli_launch_profile(tmp_path):
+    from prizmkit_runtime.config import RuntimeConfigError, load_runtime_config
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    project = tmp_path / "project"
+    pipeline = project / ".prizmkit" / "dev-pipeline"
+    pipeline.mkdir(parents=True)
+    prizmkit_dir = project / ".prizmkit"
+    (prizmkit_dir / "config.json").write_text(
+        json.dumps(
+            {
+                "ai_cli": "tclaude",
+                "ai_cli_launch": {
+                    "profile": "custom",
+                    "prompt_arg": "-i",
+                    "extra_args": ["--verbose", "--path", "two words"],
+                },
+            }
+        ),
+        encoding="utf-8",
+    )
+    paths = resolve_runtime_paths(pipeline_root=pipeline)
+
+    config = load_runtime_config(paths, env={"PATH": ""})
+
+    assert config.ai_client.command == "tclaude"
+    assert config.ai_client.platform == "custom"
+    assert config.ai_client.source == "prizmkit-config:ai_cli_launch"
+    assert config.ai_client.launch_profile is not None
+    assert config.ai_client.launch_profile.prompt_arg == "-i"
+    assert config.ai_client.launch_profile.extra_args == ("--verbose", "--path", "two words")
+
+    (prizmkit_dir / "config.json").write_text(json.dumps({"ai_cli": "tclaude"}), encoding="utf-8")
+    with pytest.raises(RuntimeConfigError, match="prompt injection argument"):
+        load_runtime_config(paths, env={"PATH": ""})
+
+
+    (prizmkit_dir / "config.json").write_text(
+        json.dumps(
+            {
+                "ai_cli": "claude",
+                "ai_cli_launch": {"profile": "custom", "prompt_arg": "-i", "extra_args": ["--stale"]},
+            }
+        ),
+        encoding="utf-8",
+    )
+    built_in = load_runtime_config(paths, env={"PATH": ""}).ai_client
+    assert built_in.command == "claude"
+    assert built_in.platform == "claude"
+    assert built_in.source == "prizmkit-config:ai_cli"
+    assert built_in.launch_profile is None
+
+    (prizmkit_dir / "config.json").write_text(
+        json.dumps({"ai_cli": "tclaude", "ai_cli_launch": {"prompt_arg": "-i"}}),
+        encoding="utf-8",
+    )
+    with pytest.raises(RuntimeConfigError, match="profile"):
+        load_runtime_config(paths, env={"PATH": ""})
+
+
+    env_override = load_runtime_config(paths, env={"AI_CLI": "claude", "PATH": ""}).ai_client
+    assert env_override.command == "claude"
+    assert env_override.platform == "claude"
+    assert env_override.source == "environment:AI_CLI"
+    assert env_override.launch_profile is None
+
+
 def test_runtime_config_supplied_env_does_not_leak_ambient_path(tmp_path):
     from prizmkit_runtime.config import load_runtime_config
     from prizmkit_runtime.paths import resolve_runtime_paths
@@ -393,7 +460,7 @@ def test_interoperability_preserves_existing_utility_mapping():
     assert actual_scripts == mapped_scripts | explicitly_library_only
     assert explicitly_library_only == {"continuation.py", "utils.py"}
     assert "parse-stream-progress.py" in mapped_scripts
-    assert "prizmkit-test-gate.py" in mapped_scripts
+    assert "prizmkit-test-gate.py" not in mapped_scripts
 
 
 def test_boundary_dataclasses_are_cohesive_and_frozen():
@@ -445,14 +512,14 @@ def test_runtime_config_loads_prizmkit_env_and_validates_effort(tmp_path):
     pipeline.mkdir(parents=True)
     prizmkit_dir = project / ".prizmkit"
     (prizmkit_dir / ".env").write_text(
-        "AI_CLI=env-claude\nPRIZMKIT_EFFORT=max\nMODEL=env-model\n",
+        "AI_CLI=claude\nPRIZMKIT_EFFORT=max\nMODEL=env-model\n",
         encoding="utf-8",
     )
     paths = resolve_runtime_paths(pipeline_root=pipeline)
 
     config = load_runtime_config(paths, env={"PATH": ""})
 
-    assert config.ai_client.command == "env-claude"
+    assert config.ai_client.command == "claude"
     assert config.ai_client.platform == "claude"
     assert config.ai_client.source == "environment:AI_CLI"
     assert config.model == "env-model"
@@ -541,6 +608,212 @@ def test_ai_session_command_builders_match_unix_runtime_snapshot(tmp_path):
     assert codebuddy.stdin_text == "hello"
 
 
+def test_custom_ai_session_command_builder_injects_prompt_and_tokenizes_extra_args(tmp_path):
+    from prizmkit_runtime.launch_profiles import HeadlessLaunchProfile
+    from prizmkit_runtime.sessions import AISessionConfig, build_ai_session_command
+
+    prompt = tmp_path / "prompt.md"
+    prompt.write_text("injected prompt", encoding="utf-8")
+    project = tmp_path / "project"
+    project.mkdir()
+
+    command = build_ai_session_command(
+        AISessionConfig(
+            cli_command="tclaude",
+            platform="custom",
+            model="ignored-model",
+            prompt_path=prompt,
+            cwd=project,
+            effort="ignored-effort",
+            use_stream_json=True,
+            launch_profile=HeadlessLaunchProfile(
+                profile="custom",
+                prompt_arg="-i",
+                extra_args=("--verbose", "--path", "two words"),
+            ),
+        )
+    )
+
+    assert command.argv == ("tclaude", "-i", "injected prompt", "--verbose", "--path", "two words")
+    assert command.stdin_text is None
+    assert command.provider == "custom"
+    assert command.prompt_mode == "argument"
+
+
+def test_start_command_serialization_redacts_prompt_and_preserves_provider_flags(tmp_path):
+    from prizmkit_runtime.launch_profiles import HeadlessLaunchProfile
+    from prizmkit_runtime.sessions import AISessionConfig, build_ai_session_command, format_start_command
+
+    prompt = tmp_path / "prompt.md"
+    secret_prompt = "secret prompt body with spaces"
+    prompt.write_text(secret_prompt, encoding="utf-8")
+    project = tmp_path / "project"
+    project.mkdir()
+
+    claude = format_start_command(
+        build_ai_session_command(
+            AISessionConfig(
+                cli_command="claude",
+                platform="claude",
+                model=None,
+                prompt_path=prompt,
+                cwd=project,
+            )
+        )
+    )
+    assert "claude -p <prompt>" in claude
+    assert "--disallowedTools EnterWorktree" in claude
+    assert secret_prompt not in claude
+
+    codebuddy = format_start_command(
+        build_ai_session_command(
+            AISessionConfig(
+                cli_command="cbc",
+                platform="codebuddy",
+                model=None,
+                prompt_path=prompt,
+                cwd=project,
+            )
+        )
+    )
+    assert codebuddy.startswith("cbc --print -y")
+    assert "--disallowedTools EnterWorktree" in codebuddy
+    assert secret_prompt not in codebuddy
+
+    codex = format_start_command(
+        build_ai_session_command(
+            AISessionConfig(
+                cli_command="codex",
+                platform="codex",
+                model=None,
+                prompt_path=prompt,
+                cwd=project,
+            )
+        )
+    )
+    assert "--profile no-worktree" in codex
+    assert "exec --cd" in codex
+    assert codex.endswith(" -")
+    assert secret_prompt not in codex
+
+    custom = format_start_command(
+        build_ai_session_command(
+            AISessionConfig(
+                cli_command="tclaude",
+                platform="custom",
+                model=None,
+                prompt_path=prompt,
+                cwd=project,
+                launch_profile=HeadlessLaunchProfile(
+                    profile="custom",
+                    prompt_arg="-i",
+                    extra_args=("--custom-flag", "two words", secret_prompt),
+                ),
+            )
+        )
+    )
+    assert custom == "tclaude -i <prompt> --custom-flag 'two words' <prompt>"
+    assert custom.count("<prompt>") == 2
+    assert secret_prompt not in custom
+
+
+def test_session_preamble_writes_redacted_start_command_for_all_launch_profiles(tmp_path, monkeypatch):
+    import prizmkit_runtime.sessions as sessions
+    from prizmkit_runtime.launch_profiles import HeadlessLaunchProfile
+
+    fake_cli = tmp_path / "fake_cli.py"
+    fake_cli.write_text(
+        "#!/usr/bin/env python3\n"
+        "import json, sys\n"
+        "_stdin = sys.stdin.read()\n"
+        "print(json.dumps({'type':'result','subtype':'success','usage':{'tokens':1},'result':'ok'}), flush=True)\n",
+        encoding="utf-8",
+    )
+    fake_cli.chmod(0o755)
+
+    backup_texts = {}
+    original_recover = sessions.recover_session_log
+
+    def spy_recover(primary, backup, min_size=1024):
+        if backup.is_file():
+            backup_texts[str(backup)] = backup.read_text(encoding="utf-8")
+        return original_recover(primary, backup, min_size)
+
+    monkeypatch.setattr(sessions, "recover_session_log", spy_recover)
+
+    cases = [
+        ("claude", "claude", None, "--disallowedTools EnterWorktree", "-p <prompt>"),
+        ("codebuddy", "codebuddy", None, "--disallowedTools EnterWorktree", "--print -y"),
+        ("codex", "codex", None, "--profile no-worktree", "exec --cd"),
+        (
+            "custom",
+            "custom",
+            HeadlessLaunchProfile(profile="custom", prompt_arg="-i", extra_args=("--custom-flag", "two words")),
+            "--custom-flag 'two words'",
+            "-i <prompt>",
+        ),
+    ]
+
+    for label, platform, launch_profile, expected_flag, expected_prompt_marker in cases:
+        secret_prompt = f"secret prompt body for {label}"
+        prompt = tmp_path / f"{label}-prompt.md"
+        prompt.write_text(secret_prompt, encoding="utf-8")
+        session_log = tmp_path / "state" / "sessions" / f"sess-{label}" / "logs" / "session.log"
+        backup_log = tmp_path / "home" / ".prizmkit" / "session-backups" / f"sess-{label}.log"
+
+        result = sessions.AISessionLauncher(
+            sessions.AISessionConfig(
+                cli_command=str(fake_cli),
+                platform=platform,
+                model=None,
+                prompt_path=prompt,
+                cwd=tmp_path,
+                log_path=session_log,
+                backup_log_path=backup_log,
+                launch_profile=launch_profile,
+            )
+        ).run()
+
+        assert result.exit_code == 0
+        primary_text = session_log.read_text(encoding="utf-8")
+        backup_text = backup_texts[str(backup_log)]
+        for text in (primary_text, backup_text):
+            lines = text.splitlines()
+            assert lines[0] == "=== PRIZMKIT SESSION START ==="
+            assert lines[1] == "Prompt: <prompt>"
+            assert lines[2] == "Model: default"
+            assert lines[3].startswith("StartCommand： ")
+            assert expected_flag in lines[3]
+            assert expected_prompt_marker in lines[3]
+            assert lines[4].startswith("Started at epoch: ")
+            assert lines[5] == "--- OUTPUT BELOW ---"
+            assert secret_prompt not in "\n".join(lines[:6])
+            assert str(prompt) not in "\n".join(lines[:6])
+
+
+def test_headless_subagent_prompt_guidance_keeps_no_worktree_boundary_visible():
+    guidance_files = [
+        REPO_ROOT / "dev-pipeline" / "templates" / "sections" / "phase-critic-plan.md",
+        REPO_ROOT / "dev-pipeline" / "templates" / "sections" / "phase-critic-plan-full.md",
+        REPO_ROOT / "dev-pipeline" / "templates" / "agent-prompts" / "critic-plan-challenge.md",
+        REPO_ROOT / "dev-pipeline" / "templates" / "bootstrap-tier2.md",
+        REPO_ROOT / "dev-pipeline" / "templates" / "bootstrap-tier3.md",
+        REPO_ROOT / "core" / "skills" / "prizmkit-skill" / "prizmkit-code-review" / "SKILL.md",
+    ]
+
+    for path in guidance_files:
+        text = path.read_text(encoding="utf-8")
+        assert "default/no worktree" in text, path
+        assert "do not request worktree isolation" in text.lower(), path
+        assert ".claude/worktrees/..." in text, path
+        assert ".prizmkit/state/worktrees/..." in text, path
+        assert "USE_WORKTREE" in text, path
+
+    for path in guidance_files[:-1]:
+        text = path.read_text(encoding="utf-8")
+        assert "Read existing source files in the modules this plan touches" not in text, path
+
+
 def test_progress_parser_adds_required_metadata(tmp_path):
     import importlib.util
 
@@ -617,6 +890,93 @@ def test_session_dual_writes_progress_and_recovers_backup(tmp_path):
     assert second_log.read_text(encoding="utf-8") == "larger recovered log"
 
 
+def test_custom_session_launch_writes_existing_logs_and_progress(tmp_path):
+    from prizmkit_runtime.launch_profiles import HeadlessLaunchProfile
+    from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher
+
+    fake_cli = tmp_path / "custom_cli.py"
+    fake_cli.write_text(
+        "#!/usr/bin/env python3\n"
+        "import json, sys\n"
+        "assert sys.argv[1] == '-i'\n"
+        "assert sys.argv[2] == 'hello custom'\n"
+        "assert sys.argv[3:] == ['--verbose', '--path', 'two words']\n"
+        "print(json.dumps({'type':'result','subtype':'success','usage':{'tokens':1},'result':'ok'}), flush=True)\n",
+        encoding="utf-8",
+    )
+    fake_cli.chmod(0o755)
+    prompt = tmp_path / "prompt.md"
+    prompt.write_text("hello custom", encoding="utf-8")
+    session_log = tmp_path / "state" / "sessions" / "sess-custom" / "logs" / "session.log"
+    progress = session_log.with_name("progress.json")
+
+    result = AISessionLauncher(
+        AISessionConfig(
+            cli_command=str(fake_cli),
+            platform="custom",
+            model=None,
+            prompt_path=prompt,
+            cwd=tmp_path,
+            log_path=session_log,
+            progress_path=progress,
+            launch_profile=HeadlessLaunchProfile(
+                profile="custom",
+                prompt_arg="-i",
+                extra_args=("--verbose", "--path", "two words"),
+            ),
+        )
+    ).run()
+
+    assert result.exit_code == 0
+    assert result.command.argv[1:4] == ("-i", "hello custom", "--verbose")
+    assert session_log.exists()
+    assert progress.exists()
+    progress_data = json.loads(progress.read_text(encoding="utf-8"))
+    assert progress_data["event_type_counts"]["result"] == 1
+    assert progress_data["has_usage"] is True
+
+
+@pytest.mark.parametrize("platform", ["claude", "codex", "codebuddy"])
+def test_builtin_provider_launches_write_session_artifacts(tmp_path, platform):
+    from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher
+
+    fake_cli = tmp_path / f"{platform}_cli.py"
+    fake_cli.write_text(
+        "#!/usr/bin/env python3\n"
+        "import json, sys\n"
+        "_stdin = sys.stdin.read()\n"
+        "print(json.dumps({'type':'result','subtype':'success','usage':{'tokens':1},'result':'ok'}), flush=True)\n",
+        encoding="utf-8",
+    )
+    fake_cli.chmod(0o755)
+    prompt = tmp_path / f"{platform}-prompt.md"
+    prompt.write_text(f"hello {platform}", encoding="utf-8")
+    session_log = tmp_path / "state" / "sessions" / f"sess-{platform}" / "logs" / "session.log"
+    progress = session_log.with_name("progress.json")
+    heartbeat = session_log.with_name("heartbeat.json")
+
+    result = AISessionLauncher(
+        AISessionConfig(
+            cli_command=str(fake_cli),
+            platform=platform,
+            model=None,
+            prompt_path=prompt,
+            cwd=tmp_path,
+            log_path=session_log,
+            progress_path=progress,
+            heartbeat_path=heartbeat,
+            use_stream_json=True,
+        )
+    ).run()
+
+    progress_data = json.loads(progress.read_text(encoding="utf-8"))
+    assert result.exit_code == 0
+    assert session_log.exists()
+    assert heartbeat.exists()
+    assert progress_data["event_type_counts"]["result"] == 1
+    assert progress_data["has_usage"] is True
+
+
 def test_session_live_output_prints_paths_and_verbose_cli_output(tmp_path, capsys):
     from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher
 
@@ -659,6 +1019,369 @@ def test_session_live_output_prints_paths_and_verbose_cli_output(tmp_path, capsy
     assert "[prizmkit] AI session finished" in captured.err
 
 
+def test_compact_progress_line_hides_stale_until_no_progress(tmp_path):
+    from prizmkit_runtime.heartbeat import HeartbeatState
+    from prizmkit_runtime.sessions import _compact_progress_line
+
+    session_log = tmp_path / "session.log"
+    progress = tmp_path / "progress.json"
+    progress.write_text(
+        json.dumps(
+            {
+                "child_total_bytes": 2 * 1024 * 1024,
+                "subagent_spawn_count": 5,
+                "current_phase": "retrospective",
+                "current_tool": "Read",
+                "message_count": 465,
+                "total_tool_calls": 412,
+            }
+        ),
+        encoding="utf-8",
+    )
+    running = HeartbeatState(last_seen_epoch=1.0, stale=False, details="progress", stale_seconds=0, log_size=4 * 1024 * 1024)
+    brief_pause = HeartbeatState(last_seen_epoch=1.0, stale=False, details="no progress", stale_seconds=125, log_size=4 * 1024 * 1024)
+    paused = HeartbeatState(last_seen_epoch=1.0, stale=True, details="no progress", stale_seconds=15 * 60, log_size=4 * 1024 * 1024)
+    resumed = HeartbeatState(last_seen_epoch=3.0, stale=False, details="progress", stale_seconds=0, log_size=5 * 1024 * 1024)
+
+    running_line = _compact_progress_line(0, session_log, progress, running, stale_threshold_seconds=15 * 60)
+    brief_pause_line = _compact_progress_line(0, session_log, progress, brief_pause, stale_threshold_seconds=15 * 60)
+    paused_line = _compact_progress_line(0, session_log, progress, paused, stale_threshold_seconds=15 * 60)
+    resumed_line = _compact_progress_line(0, session_log, progress, resumed, stale_threshold_seconds=15 * 60)
+
+    assert "▶ [HEARTBEAT]" in running_line
+    assert "log: 4MB" in running_line
+    assert "child: 2MB/5" in running_line
+    assert "phase: retrospective" in running_line
+    assert "tool: Read" in running_line
+    assert "msgs: 465" in running_line
+    assert "412 tool calls" in running_line
+    assert "stale:" not in running_line
+    assert "▶ [HEARTBEAT]" in brief_pause_line
+    assert "stale:" not in brief_pause_line
+    assert "⏸ [HEARTBEAT]" in paused_line
+    assert "stale: 15m/15m" in paused_line
+    assert "▶ [HEARTBEAT]" in resumed_line
+    assert "log: 5MB" in resumed_line
+    assert "stale:" not in resumed_line
+
+
+def test_heartbeat_observation_stale_accumulates_by_elapsed_time_and_resets_on_progress(tmp_path, monkeypatch):
+    import prizmkit_runtime.heartbeat as heartbeat
+    from prizmkit_runtime.heartbeat import HeartbeatConfig, observe_heartbeat_state
+
+    session_log = tmp_path / "session.log"
+    progress = tmp_path / "progress.json"
+    session_log.write_text("initial\n", encoding="utf-8")
+    progress.write_text('{"current_phase":"plan","current_tool":"Read","message_count":1,"total_tool_calls":1}\n', encoding="utf-8")
+    config = HeartbeatConfig(
+        heartbeat_file=tmp_path / "heartbeat.json",
+        session_log=session_log,
+        progress_file=progress,
+        interval_seconds=60,
+        stale_after_seconds=15 * 60,
+    )
+    ticks = iter([1000.0, 1025.0, 1090.0, 1095.0])
+    monkeypatch.setattr(heartbeat.time, "time", lambda: next(ticks))
+
+    first = observe_heartbeat_state(config)
+    stale = observe_heartbeat_state(config, first)
+    older = observe_heartbeat_state(config, stale)
+    progress.write_text('{"current_phase":"plan","current_tool":"Edit","message_count":1,"total_tool_calls":2,"child_total_bytes":10}\n', encoding="utf-8")
+    reset = observe_heartbeat_state(config, older)
+
+    assert first.details == "progress"
+    assert first.stale_seconds == 0
+    assert first.last_seen_epoch == 1000.0
+    assert stale.details == "no progress"
+    assert stale.stale_seconds == 25.0
+    assert older.stale_seconds == 90.0
+    assert reset.details == "progress"
+    assert reset.stale_seconds == 0
+    assert reset.last_seen_epoch == 1095.0
+
+
+
+def test_heartbeat_state_tracks_progress_json_child_activity(tmp_path, monkeypatch):
+    import prizmkit_runtime.heartbeat as heartbeat
+    from prizmkit_runtime.heartbeat import HeartbeatConfig, observe_heartbeat_state
+
+    progress = tmp_path / "progress.json"
+    progress.write_text(
+        json.dumps({"child_activity_signature": "child:1", "child_total_bytes": 10}),
+        encoding="utf-8",
+    )
+    config = HeartbeatConfig(
+        heartbeat_file=tmp_path / "heartbeat.json",
+        session_log=tmp_path / "missing-session.log",
+        progress_file=progress,
+        stale_after_seconds=60,
+    )
+    ticks = iter([10.0, 20.0, 25.0])
+    monkeypatch.setattr(heartbeat.time, "time", lambda: next(ticks))
+
+    first = observe_heartbeat_state(config)
+    quiet = observe_heartbeat_state(config, first)
+    progress.write_text(
+        json.dumps({"child_activity_signature": "child:2", "child_total_bytes": 20}),
+        encoding="utf-8",
+    )
+    child_progress = observe_heartbeat_state(config, quiet)
+
+    assert quiet.details == "no progress"
+    assert quiet.stale_seconds == 10.0
+    assert child_progress.details == "progress"
+    assert child_progress.stale_seconds == 0
+    assert child_progress.child_activity_signature == "child:2"
+
+
+def test_heartbeat_monitor_stale_kill_uses_elapsed_no_progress_threshold(tmp_path):
+    from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher
+
+    fake_cli = tmp_path / "quiet_cli.py"
+    fake_cli.write_text(
+        "#!/usr/bin/env python3\n"
+        "import time\n"
+        "time.sleep(5)\n",
+        encoding="utf-8",
+    )
+    fake_cli.chmod(0o755)
+    prompt = tmp_path / "prompt.md"
+    prompt.write_text("hello", encoding="utf-8")
+    session_log = tmp_path / "state" / "sessions" / "sess-stale" / "logs" / "session.log"
+    progress = session_log.with_name("progress.json")
+    heartbeat = session_log.with_name("heartbeat.json")
+
+    result = AISessionLauncher(
+        AISessionConfig(
+            cli_command=str(fake_cli),
+            platform="codebuddy",
+            model=None,
+            prompt_path=prompt,
+            cwd=tmp_path,
+            log_path=session_log,
+            progress_path=progress,
+            heartbeat_path=heartbeat,
+            stale_kill_threshold_seconds=0.3,
+            heartbeat_stale_threshold_seconds=0.2,
+            stale_kill_grace_seconds=0.1,
+        )
+    ).run()
+
+    marker = session_log.parent / "stale-kill.json"
+    marker_data = json.loads(marker.read_text(encoding="utf-8"))
+    assert result.termination_reason == "stale_session"
+    assert result.stale_marker == marker
+    assert marker_data["reason"] == "stale_session"
+    assert marker_data["threshold"] == pytest.approx(0.3)
+    assert marker_data["stale_seconds"] >= 0
+
+
+def test_stale_marker_preserves_subsecond_threshold(tmp_path):
+    from prizmkit_runtime.heartbeat import write_stale_marker
+
+    marker = write_stale_marker(
+        tmp_path,
+        reason="stale_session",
+        stale_seconds=0.4,
+        threshold=0.3,
+    )
+    data = json.loads(marker.read_text(encoding="utf-8"))
+
+    assert data["stale_seconds"] == pytest.approx(0.4)
+    assert data["threshold"] == pytest.approx(0.3)
+
+
+def test_idle_progress_refresh_updates_child_activity_without_parent_output(tmp_path, monkeypatch):
+    import prizmkit_runtime.sessions as sessions
+
+    progress = tmp_path / "progress.json"
+    tracker_lock = sessions.threading.Lock()
+    stop_event = sessions.threading.Event()
+
+    class FakeTracker:
+        def __init__(self):
+            self.calls = 0
+
+        def to_dict(self):
+            self.calls += 1
+            return {
+                "message_count": 1,
+                "event_type_counts": {},
+                "current_tool": "Task",
+                "current_phase": "implement",
+                "total_tool_calls": 1,
+                "active_subagent_count": 1,
+                "subagent_spawn_count": 1,
+                "child_activity_signature": f"child:{self.calls}",
+                "child_total_bytes": self.calls,
+                "fatal_error_code": "",
+                "terminal_result_text": "",
+                "errors": [],
+            }
+
+    thread, refresh = sessions._start_idle_progress_refresh(
+        progress,
+        FakeTracker(),
+        tracker_lock,
+        stop_event,
+        interval_seconds=0.1,
+    )
+    try:
+        refresh(True)
+        first = json.loads(progress.read_text(encoding="utf-8"))
+        time.sleep(0.25)
+        second = json.loads(progress.read_text(encoding="utf-8"))
+    finally:
+        stop_event.set()
+        thread.join(timeout=1)
+
+    assert first["child_activity_signature"].startswith("child:")
+    assert second["child_activity_signature"] != first["child_activity_signature"]
+    assert second["child_total_bytes"] > first["child_total_bytes"]
+
+def test_compact_live_heartbeat_stays_out_of_primary_and_backup_logs(tmp_path, capsys, monkeypatch):
+    import prizmkit_runtime.sessions as sessions
+
+    fake_cli = tmp_path / "slow_cli.py"
+    fake_cli.write_text(
+        "#!/usr/bin/env python3\n"
+        "import time\n"
+        "print('logged-payload', flush=True)\n"
+        "time.sleep(0.45)\n",
+        encoding="utf-8",
+    )
+    fake_cli.chmod(0o755)
+    prompt = tmp_path / "prompt.md"
+    prompt.write_text("hello", encoding="utf-8")
+    session_log = tmp_path / "state" / "sessions" / "sess-heartbeat" / "logs" / "session.log"
+    backup_log = tmp_path / "home" / ".prizmkit" / "session-backups" / "sess-heartbeat.log"
+    progress = session_log.with_name("progress.json")
+    backup_text = {}
+    original_recover = sessions.recover_session_log
+
+    def spy_recover(primary, backup, min_size=1024):
+        if backup.is_file():
+            backup_text["content"] = backup.read_text(encoding="utf-8")
+        return original_recover(primary, backup, min_size)
+
+    monkeypatch.setattr(sessions, "recover_session_log", spy_recover)
+    result = sessions.AISessionLauncher(
+        sessions.AISessionConfig(
+            cli_command=str(fake_cli),
+            platform="codebuddy",
+            model=None,
+            prompt_path=prompt,
+            cwd=tmp_path,
+            log_path=session_log,
+            backup_log_path=backup_log,
+            progress_path=progress,
+            live_output=True,
+            live_progress_interval_seconds=0.1,
+            stale_kill_threshold_seconds=15 * 60,
+        )
+    ).run()
+
+    captured = capsys.readouterr()
+    primary_text = session_log.read_text(encoding="utf-8")
+    assert result.exit_code == 0
+    assert "[HEARTBEAT]" in captured.err
+    assert "logged-payload" in primary_text
+    assert "[HEARTBEAT]" not in primary_text
+    assert "stale:" not in primary_text
+    assert "[HEARTBEAT]" not in backup_text.get("content", "")
+    assert "stale:" not in backup_text.get("content", "")
+
+
+def test_recovery_sessions_receive_live_heartbeat_configuration(tmp_path, monkeypatch):
+    import prizmkit_runtime.runner_recovery as runner_recovery
+
+    project = tmp_path / "project"
+    pipeline = tmp_path / "pipeline"
+    recovery_state = tmp_path / "recovery"
+    project.mkdir()
+    pipeline.mkdir()
+    recovery_state.mkdir()
+    paths = type(
+        "Paths",
+        (),
+        {"project_root": project, "pipeline_root": pipeline, "recovery_state_dir": recovery_state},
+    )()
+    captured_config = {}
+
+    monkeypatch.setattr(
+        runner_recovery,
+        "run_recovery_detect",
+        lambda _paths: (0, "{}", "", {"detected": True, "workflow_type": "feature"}),
+    )
+    monkeypatch.setattr(
+        runner_recovery,
+        "load_runtime_config",
+        lambda _paths: type(
+            "Config",
+            (),
+            {
+                "ai_client": type("Client", (), {"command": "fake-cli", "platform": "codebuddy"})(),
+                "model": "model",
+                "effort": "high",
+            },
+        )(),
+    )
+    monkeypatch.setattr(
+        runner_recovery,
+        "RunnerEnvironment",
+        type(
+            "EnvFactory",
+            (),
+            {
+                "from_env": staticmethod(
+                    lambda: type(
+                        "Env",
+                        (),
+                        {
+                            "verbose": True,
+                            "live_output": True,
+                            "heartbeat_interval_seconds": 7,
+                            "heartbeat_stale_threshold_seconds": 21,
+                            "stale_kill_threshold_seconds": 42,
+                        },
+                    )()
+                )
+            },
+        ),
+    )
+    monkeypatch.setattr(runner_recovery, "detect_stream_json_support", lambda *_args: type("Support", (), {"enabled": True})())
+    monkeypatch.setattr(
+        runner_recovery.subprocess,
+        "run",
+        lambda *_args, **_kwargs: type("Completed", (), {"returncode": 0, "stdout": "0", "stderr": ""})(),
+    )
+    monkeypatch.setattr(runner_recovery, "_recovery_outcome", lambda *_args: "no_changes")
+
+    class FakeLauncher:
+        def __init__(self, config):
+            captured_config["config"] = config
+
+        def run(self):
+            return type("Result", (), {"exit_code": 0})()
+
+    monkeypatch.setattr(runner_recovery, "AISessionLauncher", FakeLauncher)
+
+    code, stdout, stderr = runner_recovery.run_recovery(paths)
+    config = captured_config["config"]
+
+    assert code == 0
+    assert stdout == "no_changes\n"
+    assert stderr == ""
+    assert config.live_output is True
+    assert config.verbose is True
+    assert config.use_stream_json is True
+    assert config.live_progress_interval_seconds == 7
+    assert config.heartbeat_stale_threshold_seconds == 21
+    assert config.stale_kill_threshold_seconds == 42
+    assert config.live_banner is False
+    assert config.suppress_stream_output is True
+
+
 def test_session_live_output_does_not_forward_cli_output_without_verbose(tmp_path, capsys):
     from prizmkit_runtime.sessions import AISessionConfig, AISessionLauncher
 
@@ -1028,6 +1751,135 @@ def _init_temp_repo(repo):
     subprocess.run(["git", "commit", "-m", "base"], cwd=repo, check=True, stdout=subprocess.DEVNULL)
 
 
+def _head_commit_message(repo):
+    return subprocess.run(
+        ["git", "log", "-1", "--format=%s"],
+        cwd=repo,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout.strip()
+
+
+def _head_files(repo):
+    return set(
+        subprocess.run(
+            ["git", "show", "--name-only", "--format=", "HEAD"],
+            cwd=repo,
+            check=True,
+            stdout=subprocess.PIPE,
+            text=True,
+        ).stdout.split()
+    )
+
+
+def _short_status(repo):
+    return subprocess.run(
+        ["git", "status", "--short"],
+        cwd=repo,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout
+
+
+def test_preflight_ready_commit_preserves_dirty_unstaged_visible_changes(tmp_path):
+    from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
+
+    repo = tmp_path / "repo"
+    _init_temp_repo(repo)
+    (repo / "visible.txt").write_text("dirty\n", encoding="utf-8")
+
+    result = commit_preflight_ready_changes(repo, "F-001")
+
+    assert result.committed
+    assert _head_commit_message(repo) == "chore: ready for F-001"
+    assert _head_files(repo) == {"visible.txt"}
+    assert _short_status(repo) == ""
+
+
+def test_preflight_ready_commit_preserves_dirty_staged_visible_changes(tmp_path):
+    from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
+
+    repo = tmp_path / "repo"
+    _init_temp_repo(repo)
+    (repo / "staged.txt").write_text("staged\n", encoding="utf-8")
+    subprocess.run(["git", "add", "staged.txt"], cwd=repo, check=True)
+
+    result = commit_preflight_ready_changes(repo, "B-002")
+
+    assert result.committed
+    assert _head_commit_message(repo) == "chore: ready for B-002"
+    assert _head_files(repo) == {"staged.txt"}
+    assert _short_status(repo) == ""
+
+
+def test_preflight_ready_commit_skips_clean_workspace(tmp_path):
+    from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
+
+    repo = tmp_path / "repo"
+    _init_temp_repo(repo)
+    before = subprocess.run(["git", "rev-parse", "HEAD"], cwd=repo, check=True, stdout=subprocess.PIPE, text=True).stdout.strip()
+
+    result = commit_preflight_ready_changes(repo, "R-003")
+
+    after = subprocess.run(["git", "rev-parse", "HEAD"], cwd=repo, check=True, stdout=subprocess.PIPE, text=True).stdout.strip()
+    assert not result.attempted
+    assert not result.committed
+    assert after == before
+
+
+def test_preflight_ready_commit_skips_hidden_support_asset_only_changes(tmp_path):
+    from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
+
+    repo = tmp_path / "repo"
+    _init_temp_repo(repo)
+    (repo / ".claude").mkdir()
+    (repo / ".claude" / "settings.local.json").write_text("{}\n", encoding="utf-8")
+    before = subprocess.run(["git", "rev-parse", "HEAD"], cwd=repo, check=True, stdout=subprocess.PIPE, text=True).stdout.strip()
+
+    result = commit_preflight_ready_changes(repo, "F-004")
+
+    after = subprocess.run(["git", "rev-parse", "HEAD"], cwd=repo, check=True, stdout=subprocess.PIPE, text=True).stdout.strip()
+    assert not result.attempted
+    assert after == before
+    assert (repo / ".claude" / "settings.local.json").is_file()
+
+
+def test_preflight_ready_commit_excludes_already_staged_hidden_support_assets(tmp_path):
+    from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
+
+    repo = tmp_path / "repo"
+    _init_temp_repo(repo)
+    (repo / ".claude").mkdir()
+    (repo / ".claude" / "agent.md").write_text("hidden\n", encoding="utf-8")
+    subprocess.run(["git", "add", "-f", ".claude/agent.md"], cwd=repo, check=True)
+    (repo / "visible.txt").write_text("visible\n", encoding="utf-8")
+
+    result = commit_preflight_ready_changes(repo, "F-005")
+
+    assert result.committed
+    assert _head_commit_message(repo) == "chore: ready for F-005"
+    assert _head_files(repo) == {"visible.txt"}
+    assert "A  .claude/agent.md" in _short_status(repo)
+
+
+def test_preflight_ready_commit_excludes_ignored_tool_worktree_directories(tmp_path):
+    from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
+
+    repo = tmp_path / "repo"
+    _init_temp_repo(repo)
+    (repo / ".cache" / "worktrees" / "agent").mkdir(parents=True)
+    (repo / ".cache" / "worktrees" / "agent" / "artifact.txt").write_text("tool\n", encoding="utf-8")
+    (repo / "visible.txt").write_text("visible\n", encoding="utf-8")
+
+    result = commit_preflight_ready_changes(repo, "F-006")
+
+    assert result.committed
+    assert _head_files(repo) == {"visible.txt"}
+    assert (repo / ".cache" / "worktrees" / "agent" / "artifact.txt").is_file()
+
+
 def test_materialize_worktree_support_assets_copies_ignored_assets_without_retired_shell_sources(tmp_path):
     from prizmkit_runtime.gitops import (
         BranchContext,