feat(cli): add dotbot logs to view activity and the last crash (#657)

[emrahzunicaplab]

Linked issue

Closes #657

Summary of changes

Adds a dotbot logs CLI command so operators can inspect a run after its
terminal window has closed.

• dotbot logs — tail the last N events (default 50) of
  .bot/.control/activity.jsonl, human-readable. Tolerates the mixed-shape
  log: logging events carry message, typed state-change events carry
  from/to/reason.
• --tail N — override the number of events shown.
• --follow — tail the log live (Ctrl+C stops).
• --last — print the crash summary from the last fatal exit.
• The process crash trap now writes .bot/.control/last-crash.json
  (exit reason, last task, last 20 activity events) via a new
  Write-DotbotCrashSummary helper in the Dotbot.Process module.
• dotbot runtime-status surfaces the last crash summary when the runtime
  is not running (missing runtime.json or a stale PID).

Kept scoped to #657: last-crash.json is written only from the existing
crash trap (not from foreground CLI exits).

Screenshots / recordings

Testing notes

• New tests/Test-LogsCLI.ps1 (Layer 2, 30 assertions): tail rendering of
  both event shapes, --tail limiting, --last, runtime-status surfacing,
  CLI dispatch wiring, empty-state / no-.bot handling, and the
  Write-DotbotCrashSummary write path (read back via dotbot logs --last).
• Green locally: Layer 1 Compilation 373/0; Layer 2 Test-LogsCLI 30/30,
  ProcessDispatch 44/44, ProcessRegistry 20/20; Layer 3 MockClaude 19/19.
  (One unrelated Components failure is pre-existing MAX_PATH worktree noise
  on Windows.)

To try it: from an initialized project, dotbot logs, dotbot logs --tail 5,
dotbot logs --follow, and dotbot logs --last.

Checklist

• Tests added or updated
• Docs updated (if behaviour changed)
• Linked issue exists
• Follows the contribution guide

[Copilot]

Pull request overview

Adds post-run diagnostics to dotbot by introducing a dotbot logs command for human-readable tailing/following of .bot/.control/activity.jsonl, plus a persisted crash summary (.bot/.control/last-crash.json) written on fatal runtime exits and surfaced via dotbot runtime-status.

Changes:

• Add dotbot logs CLI command with --tail, --follow, and --last modes.
• Persist a best-effort crash summary on runtime crash via Write-DotbotCrashSummary, and surface it from dotbot runtime-status when the runtime isn’t running.
• Add Layer 2 coverage for the new CLI behavior and wire it into tests/Run-Tests.ps1.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/Test-LogsCLI.ps1	New Layer 2 tests covering dotbot logs tail/last and runtime-status crash surfacing.
tests/Run-Tests.ps1	Includes the new Logs CLI test in Layer 2 execution and exit-code aggregation.
src/runtime/Scripts/Invoke-DotbotProcess.ps1	Crash trap now writes a persisted crash summary on unexpected termination.
src/runtime/Modules/Dotbot.Process/Dotbot.Process.psm1	Adds Write-DotbotCrashSummary implementation to generate .control/last-crash.json.
src/runtime/Modules/Dotbot.Process/Dotbot.Process.psd1	Exports Write-DotbotCrashSummary.
src/cli/runtime-status.ps1	Surfaces last crash summary when runtime.json is missing or PID is stale.
src/cli/logs.ps1	New dotbot logs command implementation (tail/follow activity.jsonl; show last-crash.json).
README.md	Documents the new dotbot logs command.
bin/dotbot.ps1	Adds logs to help output and CLI dispatch.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 2 comments.

[carlospedreira]

Accepted follow-up scope is tracked in #670: caught fatal failures writing last-crash.json, true latest-run filtering, and incremental/performance-safe follow mode.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated no new comments.

Suppressed comments (1)

tests/Test-LogsCLI.ps1:102

• dotbot logs --follow is a user-facing mode described in the PR/README, but this test suite doesn't exercise it. Adding at least a smoke test (start logs.ps1 -Follow -PollIntervalMs 100 in a background pwsh, append a new JSONL line to activity.jsonl, assert the appended message appears, then terminate the child) would help prevent regressions in the follow loop/cursor-reset logic.

    # -------------------------------------------------------------------
    # dotbot logs — tail (mixed-shape rendering)
    # -------------------------------------------------------------------
    $r = Invoke-Cli -Script $logsScript -WorkDir $projA -CliArgs @('-Tail', '10')
    Assert-Equal -Name "logs tail exits 0" -Expected 0 -Actual $r.Code -Message $r.Output

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/runtime/Modules/Dotbot.Process/Dotbot.Process.psm1:965

• Write-DotbotCrashSummary relies on -BotRoot for all path resolution, but the parameter isn't mandatory/validated. If a caller forgets to pass it, the function will silently do nothing (the outer try/catch swallows the resulting errors), which defeats the purpose of persisting crash diagnostics.

Make BotRoot mandatory and non-empty so misuse is caught at the call site (or at least produces a deterministic parameter-binding error in non-trap contexts).

        [string]$BotRoot

src/runtime/Modules/Dotbot.Process/Dotbot.Process.psm1:980

• Write-DotbotCrashSummary reads the entire per-process activity log into memory (ReadToEnd) just to take the last $MaxEvents lines. If a process has a large .activity.jsonl, this can significantly slow down the crash trap or even OOM, reducing the likelihood that the crash summary is written when it's needed most.

Consider reading only the last chunk of the file (best-effort) before splitting into lines, then taking the last $MaxEvents entries. This keeps runtime/memory bounded while still capturing recent events.

                $stream = [System.IO.FileStream]::new($activityPath, [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileShare]::ReadWrite)
                try {
                    $reader = [System.IO.StreamReader]::new($stream, [System.Text.Encoding]::UTF8)
                    try { $text = $reader.ReadToEnd() } finally { $reader.Dispose() }
                } finally { $stream.Dispose() }

src/cli/logs.ps1:235

• In --follow mode the loop re-reads and re-splits the entire activity.jsonl on every poll (Read-ActivityLine), which makes CPU/memory usage grow with log size (O(file_size) per poll). For long-running sessions or verbose logs, this can become a noticeable performance/operational issue.

A more scalable approach is to track a byte offset (or line position) and only read newly appended data each iteration, similar to how workflow-run.ps1 streams new process activity events.

while (-not $script:DotbotLogsStopRequested) {
    Start-Sleep -Milliseconds $PollIntervalMs
    try {
        $lines = Read-ActivityLine -Path $activityPath
    } catch {
        continue

[carlospedreira]

Rebased integration reviewed and validated. Preserves both #660 kill-on-close behavior and #663 crash diagnostics; canonical-path regression coverage is consolidated from #674. Required checks are green.