Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
4.5 KiB
spec, created, status
| spec | created | status |
|---|---|---|
| docs/specs/office/agents.md | 2026-08-22 | done |
Implementation Plan: Wire the Office agent cooldown gate
Overview
PR #2902 fixed office_agent_runtime.last_run_finished_at to be stamped correctly on every
completed/stopped run (sync and async, task-bound and taskless), but explicitly scoped out two
follow-ups. This plan closes both, resolved together because they're the same underlying question
("what does the Office heartbeat cooldown gate mean?"):
- Wrong column.
heartbeatAgentRuntime.AllowFire(internal/backendapp/cron.go) readsagent_profiles.last_run_finished_at— a column from the shared kanban agent-settings table that no Office write path ever stamps — instead ofoffice_agent_runtime.last_run_finished_at, the columnService.stampRunFinishedactually maintains.agent.LastRunFinishedAt != nilis therefore always false and the cooldown branch never fires: Office heartbeat cooldown is silently a no-op today, regardless ofcooldown_sec. - Missing stamp on failure.
HandleAgentFailure(internal/office/service/failure.go) marks a run failed and releases its task checkout but never callsstampRunFinished. Once (1) is fixed, a below-threshold failing agent would be exempt from cooldown pacing entirely (unlike a successful or stopped run), letting a flapping agent retry with zero pacing until it crosses the auto-pause threshold.
Resolved spec decision (see amendments below): cooldown paces every terminal run outcome for an agent — completed, stopped, taskless-completed, and failed alike — uniformly. It is a run-pacing mechanism, not a success tracker. The separate consecutive-failure counter / auto-pause threshold remains the mechanism for stopping a chronically broken agent; cooldown only paces the failures that happen before that threshold is reached.
Out of scope: removing or migrating the dead agent_profiles.last_run_finished_at column (bigger
blast radius across the shared kanban agent-settings table; not needed to fix the bug — the gate
just needs to stop reading it). No schema change. No frontend change.
Spec amendments (already applied)
docs/specs/office/agents.md— persistence-guarantees bullet foroffice_agent_runtimenow names the exact gate (heartbeatAgentRuntime.AllowFire), states which column it must read, and explicitly calls out theagent_profilessame-named column as dead/not-authoritative.docs/specs/office/runtime.md— "Retry policy" section states that a terminal failure stamps the cooldown timestamp same as success; a new persistence-guarantee bullet and a new GIVEN/WHEN/THEN scenario cover it.
Backend
Task 01: Cooldown gate reads office_agent_runtime, not agent_profiles — done
heartbeatAgentRuntime.AllowFire currently gates on agent.LastRunFinishedAt (from
office.GetAgentInstance, i.e. agent_profiles). Change it to load the runtime row via
office.GetAgentRuntime(ctx, agentID) (already exists, returns *officesqlite.RuntimeState with
LastRunFinishedAt *time.Time, nil, nil when no row) and gate on that timestamp instead.
agent.CooldownSec still comes from agent_profiles (that field is actively written and unrelated
to this bug). No repository or schema change — GetAgentRuntime already exists and is already
exercised by other tests.
Task 02: HandleAgentFailure stamps the cooldown timestamp — done
Add a s.stampRunFinished(ctx, run) call to HandleAgentFailure (internal/office/service/failure.go),
placed after s.releaseTaskCheckoutForRun(ctx, run) and before the consecutive-failure counter
work, mirroring the completed/stopped paths' ordering (finish/mark → release checkout → stamp).
stampRunFinished is already shared, idempotent, and no-ops safely on a nil run or empty
AgentProfileID; this task is a one-line call plus a test.
Task waves
| Wave | Tasks | Parallel-safe |
|---|---|---|
| 1 | 01, 02 | Yes — disjoint files (internal/backendapp/cron.go vs internal/office/service/failure.go), disjoint test files, no shared schema/migration/generated contract. |
Default parallelism: sequential in each task file per repo convention; the table above is a human
dispatch aid, not standing authorization to delegate to subagents.
Validation
cd apps/backend && go test ./internal/backendapp/... ./internal/office/service/... ./internal/office/repository/sqlite/...
cd apps/backend && golangci-lint run ./internal/backendapp/... ./internal/office/service/... --timeout=5m