Workflow check-in redesign: spawned monitor (no daemon/hooks) + deterministic floor + advisory agent self-review (supersedes #506)

[itlackey]

Summary

Redesign the workflow agent check-in / stall-detection mechanism and step-completion validation shipped under #501/#506. A multi-agent critical review (full writeup in docs/technical/workflow-checkin-design-review.md, §"Redesign v2 — approved direction") found the as-built check-in non-functional and the akm-side LLM validation gate redundant. The owner has approved a concrete v2 direction. This issue tracks implementing it.

Why (verified defects)

Check-in is non-functional (~2/10). It is 100% pull-based: the only trigger for evaluateCheckin is the agent voluntarily running akm workflow next (src/workflows/runs.ts:227) — self-referential, so the one thing that can fire the stall check is the very thing whose absence is the stall. Plus:

• the promised "file-signal" check-in file is never written (zero writeFileSync);
• when the directive does fire it is silently dropped by the default text formatter (formatWorkflowNextPlain, src/output/text/helpers.ts:667);
• akm workflow status does not evaluate check-in despite the ADR claiming it does;
• empirical: ~10 runs stuck active/blocked, completedAt: null, never reaped.

LLM validation gate is redundant, not "mandatory/blocking". src/workflows/validate-summary.ts:85-124 is already fully fail-open (no key / offline / timeout / 429 / malformed → completes). The real problems are that it makes an akm-side LLM call at all (the driving agent is already a frontier LLM), a 120s foreground block, non-determinism on the sole blocking path, silent skips, and prompt-injection via the raw summary.

Approved v2 design

Owner constraints (locked): no external agent-harness hooks; no long-running OS service/daemon; akm makes no LLM call of its own.

A. Check-in → short-lived spawned monitor process

• startWorkflowRun spawns a hidden akm workflow monitor <runId> via Bun.spawn(detached, unref) (reuse resolveAkmInvocation); AKM_NO_MONITOR=1 prevents the in-process test harness from forking; spawn failure non-fatal; one monitor per run via monitor_pid liveness.
• Poll loop ~60s reusing evaluateCheckin/CHECKIN_STALL_MS; optional agent_pid kill(pid,0) liveness as an immediate-stall signal.
• Hard caps (≤240 polls / ≤4h wall) guarantee self-termination — never a daemon.
• On completion → exit. On stall → atomic checkin.json + append workflow_run_events + idempotent guarded reap (UPDATE … WHERE status='active' AND checkin_armed_at=<value-read-this-tick>), so a late agent complete/next wins. Reap into the existing 'failed' status + terminal_reason='stalled' (no CHECK-constraint rebuild). On-command reapStaleRunsForScope + init reaping are the crash/reboot/Windows backstop.

B. Validation → delete the akm-side judge

• Delete validate-summary.ts (+ buildDefaultSummaryJudge/summaryJudge) outright — remove the network seam.
• Only hard gate becomes a pure deterministic structural floor (non-empty, min length, criteria-keyword coverage, no placeholders) — works offline/CI by construction.
• Semantic judgment becomes an advisory agent self-review round-trip: akm emits an instruction for the agent to run an independent fresh-context review of its own changes and report back via akm workflow complete --review-verdict pass|fail --review-notes "…" (recorded, not judged by akm). enforce=false default + maxRounds ⇒ a structurally-valid summary can always complete offline (anti-wedge).

Migration 004-monitor-and-validation (additive; 001–003 untouched)

• workflow_runs += monitor_pid, agent_pid, last_seen_at, terminal_reason, checkin_path
• new table workflow_run_events(run_id, session_id, kind, reason, at) + index
• workflow_run_steps += review_requested_at, review_verdict, review_notes

Implementation sub-tasks (see doc §7)

• Render the check-in directive in default (text) output
• Delete the akm-side LLM summary judge (validate-summary.ts)
• Deterministic structural completion floor — the only hard gate
• Advisory agent self-review round-trip (--review-verdict/--review-notes)
• Short-lived spawned workflow monitor (akm workflow monitor <runId>)
• Durable checkin.json signal + idempotent reap + workflow_run_events
• On-command stale-run reaper + lifecycle cleanup
• Event heartbeat + clock-source hardening
• Session-continuity guard
• Rewrite the check-in ADR to match v2
• Migration 004-monitor-and-validation

Explicitly dropped (superseded by owner decisions): harness Stop-hook entry point, PostToolUse heartbeat hook, akm workflow reap cron job, tryLlmFeature-wrapped judge.

Supersedes the check-in/validation portions of #506.

[itlackey]

Implemented in PR #714 (merged). This covered the check-in redesign items and related orchestration hardening in the workflow execution engine; issue checklist items are now superseded by completed work in PR #714. Closing this issue as completed.

[itlackey]

Cross-reference cleanup after merge: #559 was the tracking issue for check-in redesign and is now closed as completed in PR #714. Also FYI: #506 was previously closed as superseded by this same work.