From ac614948f40434e8285a44c9de648057ace2597b Mon Sep 17 00:00:00 2001
From: hetaoBackend <hetao7@pku.edu.cn>
Date: Wed, 18 Mar 2026 14:03:19 +0800
Subject: [PATCH 1/4] Add heartbeat automation with UI and logging

---
 docs/rfc-heartbeat.md                   | 748 +++++++++++++++++++++
 docs/todo.md                            |  17 +
 taskboard-electron/src/renderer/App.jsx | 704 +++++++++++++++++++-
 taskboard.py                            | 834 +++++++++++++++++++++++-
 tests/test_heartbeat.py                 | 144 ++++
 5 files changed, 2423 insertions(+), 24 deletions(-)
 create mode 100644 docs/rfc-heartbeat.md
 create mode 100644 tests/test_heartbeat.py

diff --git a/docs/rfc-heartbeat.md b/docs/rfc-heartbeat.md
new file mode 100644
index 0000000..0b39600
--- /dev/null
+++ b/docs/rfc-heartbeat.md
@@ -0,0 +1,748 @@
+# RFC: Heartbeat Triggers in AgentForge
+
+**Status:** Draft
+**Date:** 2026-03-18
+**Author:** Codex
+
+---
+
+## Summary
+
+Introduce a new `heartbeat` resource in AgentForge for low-noise, periodic "check before acting" automation.
+
+Unlike an existing cron task, a heartbeat does not directly execute a full agent run every time it wakes up. Instead, it performs a lightweight decision step first. Only when that decision says there is actionable work does AgentForge create or resume a real task.
+
+This RFC proposes:
+
+- a dedicated heartbeat model separate from `tasks`
+- silent idle behavior by default
+- structured decision output instead of token or keyword matching
+- explicit deduplication and cooldown semantics
+- a small first version that coexists cleanly with the current scheduler
+
+---
+
+## Motivation
+
+AgentForge already supports `immediate`, `delayed`, `scheduled_at`, and `cron` tasks. Those schedules answer one question well: "when should this task run?"
+
+They do not answer a different question: "when should the system check whether a task is worth creating at all?"
+
+Today, if a user wants "every 10 minutes, check whether my repo needs review; if yes, create a review task," the closest fit is a cron task. That works, but it has undesirable behavior:
+
+- every wake-up becomes a real task run
+- empty checks pollute task history and output history
+- idle cycles create noise in channels and UI
+- deduplication has to be reimplemented in prompt logic
+
+Heartbeat addresses this gap by introducing a higher-level trigger primitive:
+
+- `cron task`: execute on schedule
+- `heartbeat`: inspect on schedule, then decide whether to execute
+
+This design is inspired by the recent heartbeat redesign in `HKUDS/nanobot`, whose release notes describe moving from fragile token detection to a virtual decision mechanism and making heartbeat truly silent when idle.
+
+References:
+
+- [HKUDS/nanobot](https://github.com/HKUDS/nanobot)
+- [nanobot v0.1.4.post2 release notes](https://newreleases.io/project/github/HKUDS/nanobot/release/v0.1.4.post2)
+
+---
+
+## Goals
+
+- Provide a first-class abstraction for periodic inspection that does not always create a task.
+- Keep idle heartbeat cycles invisible to the main kanban flow by default.
+- Reuse the existing AgentForge scheduler, task execution, and MessageBus architecture.
+- Make trigger decisions structured, testable, and debuggable.
+- Prevent repeated wake-ups from creating duplicate tasks for the same signal.
+
+---
+
+## Non-Goals
+
+- Replace the existing cron scheduling system.
+- Replace `/api/health` or any process liveness check.
+- Build a general-purpose workflow engine in v1.
+- Add complex multi-step self-orchestration inside heartbeat itself.
+- Expose every idle tick as a full task or full run.
+
+---
+
+## Background
+
+AgentForge's current scheduler is task-centric. A task is persisted in SQLite, moved through statuses such as `pending`, `scheduled`, `running`, `completed`, and `failed`, and accumulates task runs plus output events.
+
+That model is correct for real executions, but it is too heavy for a "watcher" abstraction. A watcher needs a lightweight place to store:
+
+- when it last checked
+- what it decided
+- why it stayed idle
+- which signal it already triggered on
+
+If heartbeat is modeled as a normal cron task, AgentForge loses the ability to distinguish:
+
+- "I checked and nothing needed to happen"
+- "I executed real work"
+
+That distinction is the main reason heartbeat should be a separate concept.
+
+---
+
+## Terminology
+
+### Heartbeat
+
+A persistent configuration that describes:
+
+- when to wake up
+- what to inspect
+- how to decide whether work is needed
+- what action to take if the decision is positive
+
+### Tick
+
+A single execution of a heartbeat's periodic check.
+
+### Decision
+
+The structured output of a tick, describing whether the heartbeat stayed idle, created work, resumed work, notified a user, or failed.
+
+### Action
+
+The concrete side effect taken after a non-idle decision, such as creating a task.
+
+---
+
+## Cron vs Heartbeat
+
+The distinction is central to this RFC.
+
+### Cron task
+
+A cron task is a real task whose schedule happens to be recurring.
+
+Properties:
+
+- wakes up on schedule
+- always executes real agent work
+- always creates a task run
+- always writes output history
+- always participates in normal task lifecycle
+
+It answers:
+
+- "When should this task run again?"
+
+### Heartbeat
+
+A heartbeat is a trigger resource that may or may not produce a task.
+
+Properties:
+
+- wakes up on schedule
+- performs a decision step first
+- only creates or resumes a real task when needed
+- stays silent when idle
+- tracks trigger-level history separately from task history
+
+It answers:
+
+- "When should the system check whether there is work worth creating?"
+
+### Practical example
+
+Requirement:
+
+"Every 10 minutes, check whether there are new commits in this repo that have not been reviewed. If yes, create a review task. If not, do nothing."
+
+With cron:
+
+- a real task runs every 10 minutes
+- most runs may be empty
+- the board fills with no-op history
+
+With heartbeat:
+
+- the heartbeat ticks every 10 minutes
+- idle ticks remain internal
+- only meaningful changes create real tasks
+
+---
+
+## Design Principles
+
+### 1. Silent When Idle
+
+An idle heartbeat should not create a task, a run, or user-facing notification by default.
+
+It may still update internal metadata such as:
+
+- `last_tick_at`
+- `last_decision`
+- `last_error`
+
+### 2. Decision Before Action
+
+Heartbeat exists to separate "inspection" from "execution." The system must never assume that a scheduled wake-up implies real work.
+
+### 3. Structured Over Heuristic
+
+Decision output must be structured JSON, not a magic token such as `HEARTBEAT_OK` and not regex matching over free-form text.
+
+This makes behavior:
+
+- explicit
+- testable
+- less fragile
+
+### 4. Low-Noise Observability
+
+Heartbeat must remain debuggable without polluting the main task board.
+
+### 5. Reuse Existing Execution Paths
+
+Once a heartbeat decides that real work is needed, it should hand off to the existing task pipeline rather than inventing a second task execution system.
+
+### 6. State Lives in Storage, Not Session
+
+Heartbeat is primarily a trigger mechanism, not a long-running conversation.
+
+Its persistent state should therefore live in AgentForge's own storage layer, not in an ever-growing model session. The system should remember heartbeat progress through explicit fields such as:
+
+- `last_tick_at`
+- `last_decision`
+- `last_triggered_at`
+- `last_dedupe_key`
+- tick history
+
+This keeps heartbeat behavior deterministic, debuggable, and inexpensive over long periods of time.
+
+---
+
+## Proposed Model
+
+### New resource type: `heartbeat`
+
+Heartbeat is a first-class resource, persisted separately from `tasks`.
+
+Each heartbeat contains:
+
+- identity and status
+- schedule
+- check definition
+- action template
+- deduplication metadata
+- last known results
+
+### Decision types
+
+The decision layer should support this enum:
+
+- `idle`
+- `trigger_task`
+- `resume_task`
+- `notify_only`
+- `error`
+
+For v1, AgentForge only needs to implement:
+
+- `idle`
+- `trigger_task`
+- `error`
+
+The others can be reserved for future expansion.
+
+### Session strategy
+
+Heartbeat should support a session policy, but the default must be stateless.
+
+Recommended model:
+
+- `stateless`: every decision tick runs in a fresh session
+- `sticky`: future option for specialized long-running heartbeat patterns
+
+V1 recommendation:
+
+- implement heartbeat decision ticks as `stateless` only
+
+Rationale:
+
+- avoids unbounded context growth
+- avoids stale or polluted decision context
+- keeps trigger behavior reproducible
+- ensures deduplication depends on explicit database state rather than hidden model memory
+
+Important distinction:
+
+- heartbeat decision state belongs in heartbeat tables
+- task execution state may still use normal task `session_id` / resume behavior after a heartbeat creates a real task
+
+---
+
+## Data Model
+
+### `heartbeats`
+
+Suggested columns:
+
+```text
+id INTEGER PRIMARY KEY
+name TEXT NOT NULL
+enabled INTEGER NOT NULL DEFAULT 1
+working_dir TEXT NOT NULL
+schedule_type TEXT NOT NULL            -- 'cron' | 'interval'
+cron_expr TEXT
+interval_seconds INTEGER
+check_prompt TEXT NOT NULL
+action_prompt_template TEXT
+default_agent TEXT DEFAULT 'claude'
+cooldown_seconds INTEGER DEFAULT 0
+last_tick_at TEXT
+last_decision TEXT
+last_error TEXT
+last_triggered_at TEXT
+last_dedupe_key TEXT
+created_at TEXT NOT NULL
+updated_at TEXT NOT NULL
+```
+
+Notes:
+
+- `schedule_type` is intentionally narrower than tasks in v1.
+- `action_prompt_template` is only used if the decision says to create a task.
+- `last_dedupe_key` is a convenience field for quick visibility, not the source of truth.
+
+### `heartbeat_ticks`
+
+Suggested columns:
+
+```text
+id INTEGER PRIMARY KEY
+heartbeat_id INTEGER NOT NULL
+started_at TEXT NOT NULL
+finished_at TEXT
+status TEXT NOT NULL                   -- 'idle' | 'triggered' | 'error'
+decision_type TEXT
+decision_payload TEXT
+task_id INTEGER
+error TEXT
+FOREIGN KEY (heartbeat_id) REFERENCES heartbeats(id)
+FOREIGN KEY (task_id) REFERENCES tasks(id)
+```
+
+Purpose:
+
+- preserve lightweight audit history
+- keep heartbeat history separate from task runs
+- support UI inspection and debugging
+
+### Optional `heartbeat_dedup`
+
+This table is optional in v1, but likely useful:
+
+```text
+id INTEGER PRIMARY KEY
+heartbeat_id INTEGER NOT NULL
+dedupe_key TEXT NOT NULL
+task_id INTEGER
+triggered_at TEXT NOT NULL
+UNIQUE(heartbeat_id, dedupe_key)
+```
+
+This makes cooldown and repeated-trigger suppression easier to implement correctly.
+
+---
+
+## Decision Contract
+
+Heartbeat decisions should be returned as JSON.
+
+### Idle example
+
+```json
+{
+  "decision": "idle",
+  "reason": "No actionable change detected",
+  "dedupe_key": "repo:/Users/me/project:head:abc123",
+  "title": "",
+  "prompt": "",
+  "metadata": {}
+}
+```
+
+### Trigger example
+
+```json
+{
+  "decision": "trigger_task",
+  "reason": "Found 3 changed files since last reviewed commit",
+  "dedupe_key": "repo:/Users/me/project:review:abc123",
+  "title": "Review latest changes in project",
+  "prompt": "Review the latest changes since commit abc123 and summarize risks, regressions, and missing tests.",
+  "metadata": {
+    "source": "heartbeat",
+    "heartbeat_id": 12
+  }
+}
+```
+
+### Error example
+
+```json
+{
+  "decision": "error",
+  "reason": "Git command failed: repository not found",
+  "dedupe_key": "",
+  "title": "",
+  "prompt": "",
+  "metadata": {}
+}
+```
+
+### Required fields
+
+- `decision`
+- `reason`
+- `dedupe_key`
+- `title`
+- `prompt`
+- `metadata`
+
+### Why structured output matters
+
+This avoids several classes of failure:
+
+- ambiguous free-form outputs
+- accidental token collisions
+- brittle string matching in multiple languages
+- hidden prompt regressions when model behavior changes
+
+---
+
+## Scheduler Behavior
+
+Heartbeat should run alongside the current task scheduler, but not as a normal task.
+
+### Tick lifecycle
+
+1. Scheduler finds due heartbeats.
+2. For each due heartbeat, AgentForge creates a `heartbeat_tick` record.
+3. The heartbeat executes a decision step.
+4. AgentForge parses and validates the decision JSON.
+5. The system checks cooldown and dedupe constraints.
+6. If the decision is `idle`, mark the tick idle and update heartbeat metadata.
+7. If the decision is `trigger_task`, create a real task through the existing task submission path.
+8. Mark the tick as `triggered` and associate it with the created task.
+9. If any step fails, mark the tick as `error`.
+
+### Session behavior during a tick
+
+For v1, the decision step of a heartbeat tick should always execute in a fresh session.
+
+That means:
+
+- no heartbeat-level `session_id` is persisted or resumed
+- decision consistency relies on persisted heartbeat metadata and tick history
+- if a tick triggers a real task, that task may then use its own normal session semantics
+
+This preserves a clean separation:
+
+- heartbeat checks for work
+- tasks carry conversational or execution continuity
+
+### Concurrency
+
+As with tasks, a heartbeat should not have overlapping active ticks unless explicitly enabled in the future.
+
+V1 rule:
+
+- one active tick per heartbeat at a time
+
+### Failure behavior
+
+A failed heartbeat tick should not automatically create a failed task. It should remain a heartbeat-level error unless a future policy says otherwise.
+
+---
+
+## Deduplication and Cooldown
+
+Heartbeat needs explicit trigger suppression. This is one of the biggest differences from cron.
+
+### Definitions
+
+- `dedupe_key`: identity of the external signal that triggered action
+- `cooldown_seconds`: minimum time before the same signal may trigger again
+
+### Rules
+
+If a decision returns `trigger_task`, AgentForge should suppress that trigger when:
+
+- the same `heartbeat_id + dedupe_key` was already triggered inside cooldown
+- the previously created task for that `dedupe_key` is still `pending`, `scheduled`, `blocked`, or `running`
+
+### Result
+
+The heartbeat may still record the tick, but the action is downgraded to `idle` with a reason such as:
+
+- "Suppressed duplicate signal during cooldown"
+
+---
+
+## Action Dispatch
+
+When a heartbeat decides to act, it should dispatch through existing code paths.
+
+### `trigger_task`
+
+Use the normal task creation path with metadata that records heartbeat provenance.
+
+Suggested metadata fields:
+
+- `source = "heartbeat"`
+- `heartbeat_id`
+- `heartbeat_tick_id`
+- `dedupe_key`
+
+This preserves a clean boundary:
+
+- heartbeat decides
+- task system executes
+
+### `resume_task`
+
+Reserved for future versions. The likely use case is reviving a waiting conversational task when a heartbeat detects new context.
+
+### `notify_only`
+
+Reserved for future versions. This would route through MessageBus without creating a task.
+
+---
+
+## API Proposal
+
+Suggested endpoints:
+
+- `GET /api/heartbeats`
+- `POST /api/heartbeats`
+- `GET /api/heartbeats/{id}`
+- `PUT /api/heartbeats/{id}`
+- `DELETE /api/heartbeats/{id}`
+- `POST /api/heartbeats/{id}/run-now`
+- `POST /api/heartbeats/{id}/pause`
+- `POST /api/heartbeats/{id}/resume`
+- `GET /api/heartbeats/{id}/ticks`
+
+### Example create payload
+
+```json
+{
+  "name": "Repo review watcher",
+  "working_dir": "~/projects/myapp",
+  "schedule_type": "interval",
+  "interval_seconds": 600,
+  "check_prompt": "Check whether there are new commits since the last reviewed commit. Return heartbeat decision JSON only.",
+  "action_prompt_template": "Review the latest code changes and summarize bugs, regressions, and missing tests.",
+  "default_agent": "claude",
+  "cooldown_seconds": 1800,
+  "enabled": true
+}
+```
+
+### Example response
+
+```json
+{
+  "id": 12,
+  "name": "Repo review watcher",
+  "enabled": true,
+  "schedule_type": "interval",
+  "interval_seconds": 600,
+  "last_tick_at": "2026-03-18T10:30:00",
+  "last_decision": "idle",
+  "last_triggered_at": "2026-03-18T09:40:00"
+}
+```
+
+---
+
+## UI Proposal
+
+Heartbeat should not be rendered as ordinary cards in the existing Queue / Running / Done columns.
+
+Suggested UI treatment:
+
+- a dedicated `Heartbeats` tab or panel
+- compact list view rather than kanban
+- one row per heartbeat
+
+Suggested columns:
+
+- name
+- enabled / paused
+- schedule
+- next tick
+- last decision
+- last triggered task
+- last error
+
+Suggested actions:
+
+- run now
+- pause / resume
+- edit
+- view recent ticks
+
+### Tick inspection
+
+The heartbeat detail view should show recent ticks with:
+
+- time
+- decision
+- reason
+- dedupe key
+- linked task, if any
+- error, if any
+
+Idle ticks should be visible in heartbeat details, but not in the main task board by default.
+
+---
+
+## Observability
+
+Heartbeat should be observable without becoming noisy.
+
+### Internal visibility
+
+Store:
+
+- last tick time
+- last decision
+- last trigger time
+- last error
+- recent ticks
+
+### Logging
+
+Recommended log levels:
+
+- `debug`: decision payloads, suppressed duplicates
+- `info`: actual task-triggering events
+- `warning`: malformed decisions, repeated scheduler anomalies
+- `error`: execution failures
+
+### Notifications
+
+By default:
+
+- idle heartbeat ticks do not notify users
+- triggered tasks behave like normal tasks and may notify via existing channels
+
+---
+
+## Security and Safety Considerations
+
+Heartbeat introduces recurring automated inspection and therefore deserves guardrails.
+
+### Prompt safety
+
+Heartbeat decision prompts should be constrained to return JSON only.
+
+### Working directory safety
+
+Heartbeat should reuse the same working directory safety assumptions already enforced for normal task execution.
+
+### Runaway automation
+
+Cooldown and dedupe exist partly as correctness features, but also as safety features to avoid accidental flood behavior.
+
+### User visibility
+
+Because heartbeat may create tasks on its own, the UI should always show:
+
+- what heartbeat created the task
+- why it triggered
+
+---
+
+## Alternatives Considered
+
+### 1. Use cron tasks only
+
+Rejected because it conflates "check" with "execute" and creates excessive no-op runs.
+
+### 2. Add a boolean flag to cron tasks, such as `silent_if_noop`
+
+Rejected because it still overloads the task abstraction. The system would have to infer or special-case whether a task actually "did nothing," which is much less explicit than a dedicated heartbeat resource.
+
+### 3. Parse a magic token from free-form output
+
+Rejected because it is fragile, hard to validate, and too easy to regress as prompts evolve.
+
+### 4. Emit every heartbeat tick as a task card
+
+Rejected because it undermines the entire goal of low-noise monitoring.
+
+---
+
+## Rollout Plan
+
+### Phase 1: Minimal viable heartbeat
+
+Scope:
+
+- heartbeat CRUD
+- schedule types: `cron` and `interval`
+- decision types: `idle`, `trigger_task`, `error`
+- tick history
+- dedupe and cooldown
+- basic UI list and tick inspection
+
+No support yet for:
+
+- `resume_task`
+- `notify_only`
+- custom tool APIs for decision logic
+- channel-specific routing policies
+
+### Phase 2: Richer actions
+
+Potential additions:
+
+- resume existing task
+- direct channel notifications
+- richer per-heartbeat policies
+- heartbeat-specific templates for common watcher types
+
+### Phase 3: Advanced policies
+
+Potential additions:
+
+- backlog thresholds
+- max tasks per day
+- dependency-aware heartbeats
+- per-channel or per-user routing
+
+---
+
+## Open Questions
+
+1. Should idle ticks be persisted indefinitely, or should AgentForge retain only the last N ticks per heartbeat?
+2. Should heartbeat creation be limited to the desktop UI first, or should chat channels be allowed to create them too?
+3. Should `trigger_task` create a brand-new task every time, or optionally update/reuse an existing open task for the same dedupe key?
+4. Should v1 expose only stateless heartbeat decisions, or should a sticky-session mode be designed now but left unimplemented?
+5. Should heartbeat-created tasks be visually marked in the main board, for example with a `heartbeat` badge?
+
+---
+
+## Recommendation
+
+Implement heartbeat as a separate first-class resource rather than as a modified cron task.
+
+This keeps the mental model clean:
+
+- tasks represent real work
+- cron defines when real work runs
+- heartbeat defines when the system checks whether real work should exist
+
+That separation makes AgentForge better suited for proactive automation without turning the board into a history of empty checks.
diff --git a/docs/todo.md b/docs/todo.md
index 454e395..8acea6f 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -1,5 +1,22 @@
 # AgentForge TODO
 
+## In Progress
+
+- [x] **Install superpowers for Codex** — followed `https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md`
+  - ✅ Cloned `obra/superpowers` to `~/.codex/superpowers`
+  - ✅ Created `~/.agents/skills/superpowers` symlink to `~/.codex/superpowers/skills`
+  - ✅ Verified symlink with `ls -la ~/.agents/skills/superpowers`
+- [x] **起草 Heartbeat RFC** — 明确 heartbeat 与现有 cron task 的边界、数据模型、调度行为和第一版实现范围
+  - ✅ 已完成：新增 `docs/rfc-heartbeat.md`，覆盖目标/非目标、cron vs heartbeat、数据模型、决策协议、调度与去重、API/UI 草案和 rollout plan
+- [x] **实现 Heartbeat MVP** — 提供后端调度、decision tick、REST API 和 macOS App 管理界面
+  - ✅ 后端：新增 heartbeat schema、ticks、dedupe、scheduler decision tick 和 `/api/heartbeats*` 端点
+  - ✅ 前端：新增 Tasks / Heartbeats 双视图、Heartbeat 创建/编辑 modal、run/pause/resume/delete 操作和 tick detail panel
+  - ✅ 验证：`uv run pytest tests/test_heartbeat.py -q` 通过，renderer `vite build` 通过
+- [x] **增加 Heartbeat Tick 日志观测性** — 支持查看 running/completed heartbeat tick 的实时输出与历史日志
+  - ✅ 后端：heartbeat tick 新增 `raw_output` 持久化和 live output cache，提供 `/api/heartbeats/:id/ticks/:tick_id/output`
+  - ✅ 前端：Heartbeat detail 新增 Tick Log 面板，可查看选中 tick 的实时日志和历史输出
+  - ✅ 验证：`uv run pytest tests/test_heartbeat.py -q` 通过，renderer `vite build` 通过
+
 ## Critical - Security
 
 - [x] **SQL 注入防护** — `taskboard.py:319` `update_task` 方法中 kwargs key 直接拼入 SQL，需对列名做白名单校验
diff --git a/taskboard-electron/src/renderer/App.jsx b/taskboard-electron/src/renderer/App.jsx
index 6a32eb0..b0cc8f2 100644
--- a/taskboard-electron/src/renderer/App.jsx
+++ b/taskboard-electron/src/renderer/App.jsx
@@ -319,6 +319,12 @@ async function fetchTasks() {
   return res.json();
 }
 
+async function fetchHeartbeats() {
+  const res = await fetch(`${API}/heartbeats`);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return res.json();
+}
+
 async function createTask(data) {
   const res = await fetch(`${API}/tasks`, {
     method: "POST", headers: await csrfHeaders(),
@@ -327,6 +333,73 @@ async function createTask(data) {
   return res.json();
 }
 
+async function createHeartbeat(data) {
+  const res = await fetch(`${API}/heartbeats`, {
+    method: "POST", headers: await csrfHeaders(),
+    body: JSON.stringify(data),
+  });
+  const payload = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(payload.error || `HTTP ${res.status}`);
+  return payload;
+}
+
+async function updateHeartbeat(id, data) {
+  const res = await fetch(`${API}/heartbeats/${id}`, {
+    method: "PUT", headers: await csrfHeaders(),
+    body: JSON.stringify(data),
+  });
+  const payload = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(payload.error || `HTTP ${res.status}`);
+  return payload;
+}
+
+async function deleteHeartbeat(id) {
+  const res = await fetch(`${API}/heartbeats/${id}`, {
+    method: "DELETE", headers: await csrfHeaders(),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+}
+
+async function runHeartbeatNow(id) {
+  const res = await fetch(`${API}/heartbeats/${id}/run-now`, {
+    method: "POST", headers: await csrfHeaders(),
+  });
+  const payload = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(payload.error || `HTTP ${res.status}`);
+  return payload;
+}
+
+async function pauseHeartbeat(id) {
+  const res = await fetch(`${API}/heartbeats/${id}/pause`, {
+    method: "POST", headers: await csrfHeaders(),
+  });
+  const payload = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(payload.error || `HTTP ${res.status}`);
+  return payload;
+}
+
+async function resumeHeartbeatApi(id) {
+  const res = await fetch(`${API}/heartbeats/${id}/resume`, {
+    method: "POST", headers: await csrfHeaders(),
+  });
+  const payload = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(payload.error || `HTTP ${res.status}`);
+  return payload;
+}
+
+async function fetchHeartbeatTicks(id) {
+  const res = await fetch(`${API}/heartbeats/${id}/ticks?limit=20`);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const payload = await res.json();
+  return payload.ticks || [];
+}
+
+async function fetchHeartbeatTickOutput(heartbeatId, tickId) {
+  const res = await fetch(`${API}/heartbeats/${heartbeatId}/ticks/${tickId}/output`);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return res.json();
+}
+
 async function cancelTask(id) {
   await fetch(`${API}/tasks/${id}/cancel`, { method: "POST", headers: await csrfHeaders() });
 }
@@ -648,6 +721,428 @@ function Column({ col, tasks, onAction, onViewDetail }) {
   );
 }
 
+function HeartbeatBadge({ enabled }) {
+  return (
+    <span style={{
+      display: "inline-flex", alignItems: "center", gap: 5,
+      padding: "3px 10px", borderRadius: 20, fontSize: 11, fontWeight: 600,
+      color: enabled ? theme.green : theme.textMuted,
+      background: enabled ? theme.greenBg : "rgba(107,107,138,0.08)",
+      letterSpacing: 0.3,
+    }}>
+      <span style={{ fontSize: 10 }}>{enabled ? "●" : "◌"}</span>
+      {enabled ? "Enabled" : "Paused"}
+    </span>
+  );
+}
+
+function HeartbeatModal({ onClose, onSubmit, initialData, defaultAgent, mode = "create" }) {
+  const savedDir = localStorage.getItem("agentforge_working_dir") || "~/papers";
+  const [form, setForm] = useState(() => ({
+    name: initialData?.name || "",
+    working_dir: initialData?.working_dir || savedDir,
+    schedule_type: initialData?.schedule_type || "interval",
+    interval_seconds: initialData?.interval_seconds || 600,
+    cron_expr: initialData?.cron_expr || "",
+    check_prompt: initialData?.check_prompt || "",
+    action_prompt_template: initialData?.action_prompt_template || "",
+    default_agent: initialData?.default_agent || defaultAgent || "claude",
+    cooldown_seconds: initialData?.cooldown_seconds || 1800,
+    enabled: initialData?.enabled ?? true,
+  }));
+
+  const set = (k, v) => setForm(prev => ({ ...prev, [k]: v }));
+
+  const inputStyle = {
+    width: "100%", padding: "10px 14px", borderRadius: 8,
+    border: `1px solid ${theme.border}`, background: theme.bg,
+    color: theme.text, fontSize: 13, outline: "none", boxSizing: "border-box",
+    fontFamily: "'JetBrains Mono', 'SF Mono', monospace",
+  };
+  const labelStyle = {
+    fontSize: 11, fontWeight: 600, color: theme.textMuted,
+    letterSpacing: 0.8, textTransform: "uppercase", marginBottom: 6, display: "block",
+  };
+
+  const handleSubmit = () => {
+    localStorage.setItem("agentforge_working_dir", form.working_dir);
+    onSubmit({
+      ...form,
+      name: form.name || "Untitled heartbeat",
+      interval_seconds: form.schedule_type === "interval" ? parseInt(form.interval_seconds) || 600 : null,
+      cooldown_seconds: parseInt(form.cooldown_seconds) || 0,
+      cron_expr: form.schedule_type === "cron" ? form.cron_expr : null,
+    });
+  };
+
+  return (
+    <div style={{
+      position: "fixed", inset: 0, background: "rgba(0,0,0,0.7)",
+      display: "flex", alignItems: "center", justifyContent: "center",
+      zIndex: 1000, backdropFilter: "blur(8px)",
+    }} onClick={onClose}>
+      <div onClick={e => e.stopPropagation()} style={{
+        background: theme.surface, border: `1px solid ${theme.border}`,
+        borderRadius: 16, padding: 32, width: 640, maxHeight: "84vh",
+        overflow: "auto", boxShadow: "0 24px 80px rgba(0,0,0,0.5)",
+      }}>
+        <h2 style={{
+          margin: "0 0 24px", fontSize: 18, fontWeight: 700, color: theme.text,
+          fontFamily: "'JetBrains Mono', monospace",
+        }}>
+          {mode === "edit" ? "Edit Heartbeat" : "New Heartbeat"}
+        </h2>
+        <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+          <div>
+            <label style={labelStyle}>Name</label>
+            <input style={inputStyle} value={form.name} onChange={e => set("name", e.target.value)} placeholder="Repo review watcher" />
+          </div>
+          <div>
+            <label style={labelStyle}>Working Directory</label>
+            <div style={{ display: "flex", gap: 8 }}>
+              <input style={{ ...inputStyle, flex: 1 }} value={form.working_dir} onChange={e => set("working_dir", e.target.value)} />
+              {window.electronAPI?.selectDirectory && (
+                <button onClick={async () => {
+                  const dir = await window.electronAPI.selectDirectory();
+                  if (dir) set("working_dir", dir);
+                }} style={{
+                  padding: "8px 14px", borderRadius: 8, cursor: "pointer",
+                  border: `1px solid ${theme.border}`, background: theme.bg,
+                  color: theme.textMuted, fontSize: 12, fontWeight: 600, whiteSpace: "nowrap",
+                }}>
+                  Browse
+                </button>
+              )}
+            </div>
+          </div>
+          <div>
+            <label style={labelStyle}>Schedule Type</label>
+            <div style={{ display: "flex", gap: 8 }}>
+              {["interval", "cron"].map(t => (
+                <button key={t} onClick={() => set("schedule_type", t)} style={{
+                  flex: 1, padding: "8px 12px", borderRadius: 8, cursor: "pointer",
+                  border: `1px solid ${form.schedule_type === t ? theme.accent : theme.border}`,
+                  background: form.schedule_type === t ? theme.accentGlow : "transparent",
+                  color: form.schedule_type === t ? theme.accent : theme.textMuted,
+                  fontSize: 12, fontWeight: 600, textTransform: "capitalize",
+                }}>
+                  {t === "interval" ? "⟳ Interval" : "⏲ Cron"}
+                </button>
+              ))}
+            </div>
+          </div>
+          {form.schedule_type === "interval" ? (
+            <div>
+              <label style={labelStyle}>Interval (seconds)</label>
+              <input type="number" style={inputStyle} value={form.interval_seconds} onChange={e => set("interval_seconds", e.target.value)} />
+            </div>
+          ) : (
+            <div>
+              <label style={labelStyle}>Cron Expression</label>
+              <input style={inputStyle} value={form.cron_expr} onChange={e => set("cron_expr", e.target.value)} placeholder="*/10 * * * *" />
+            </div>
+          )}
+          <div>
+            <label style={labelStyle}>Decision Prompt *</label>
+            <textarea
+              style={{ ...inputStyle, height: 110, resize: "vertical" }}
+              value={form.check_prompt}
+              onChange={e => set("check_prompt", e.target.value)}
+              placeholder="Check whether there are new meaningful code changes that deserve a review task. Return JSON only."
+            />
+          </div>
+          <div>
+            <label style={labelStyle}>Triggered Task Prompt Template</label>
+            <textarea
+              style={{ ...inputStyle, height: 90, resize: "vertical" }}
+              value={form.action_prompt_template}
+              onChange={e => set("action_prompt_template", e.target.value)}
+              placeholder="Review the latest code changes and summarize bugs, regressions, and missing tests."
+            />
+          </div>
+          <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 12 }}>
+            <div>
+              <label style={labelStyle}>Default Agent</label>
+              <select style={inputStyle} value={form.default_agent} onChange={e => set("default_agent", e.target.value)}>
+                {Object.entries(AGENTS).map(([key, cfg]) => <option key={key} value={key}>{cfg.label}</option>)}
+              </select>
+            </div>
+            <div>
+              <label style={labelStyle}>Cooldown (seconds)</label>
+              <input type="number" style={inputStyle} value={form.cooldown_seconds} onChange={e => set("cooldown_seconds", e.target.value)} />
+            </div>
+          </div>
+          <label style={{ display: "flex", alignItems: "center", gap: 10, fontSize: 13, color: theme.textMuted }}>
+            <input type="checkbox" checked={!!form.enabled} onChange={e => set("enabled", e.target.checked)} />
+            Enabled
+          </label>
+        </div>
+        <div style={{ display: "flex", gap: 10, justifyContent: "flex-end", marginTop: 24 }}>
+          <button onClick={onClose} style={{
+            padding: "10px 20px", borderRadius: 8, border: `1px solid ${theme.border}`,
+            background: "transparent", color: theme.textMuted, cursor: "pointer",
+            fontSize: 13, fontWeight: 600,
+          }}>Cancel</button>
+          <button onClick={handleSubmit} style={{
+            padding: "10px 24px", borderRadius: 8, border: "none",
+            background: theme.accent, color: "#fff", cursor: "pointer",
+            fontSize: 13, fontWeight: 600, boxShadow: `0 0 20px ${theme.accentGlow}`,
+          }}>
+            {mode === "edit" ? "Save" : "Create Heartbeat"}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function HeartbeatCard({ heartbeat, onAction, onViewDetail }) {
+  const tags = [];
+  if (heartbeat.schedule_type === "interval" && heartbeat.interval_seconds) tags.push(`⟳ ${heartbeat.interval_seconds}s`);
+  if (heartbeat.schedule_type === "cron" && heartbeat.cron_expr) tags.push(`⏲ ${heartbeat.cron_expr}`);
+  if (heartbeat.last_decision) tags.push(`Last: ${heartbeat.last_decision}`);
+
+  return (
+    <div
+      onClick={() => onViewDetail(heartbeat)}
+      style={{
+        background: theme.surface, border: `1px solid ${theme.border}`,
+        borderRadius: 12, padding: "16px 18px", cursor: "pointer",
+        transition: "all 0.2s ease",
+      }}
+    >
+      <div style={{ display: "flex", justifyContent: "space-between", gap: 16, marginBottom: 8 }}>
+        <div style={{ flex: 1 }}>
+          <div style={{
+            fontSize: 14, fontWeight: 700, color: theme.text,
+            fontFamily: "'JetBrains Mono', monospace", marginBottom: 6,
+          }}>
+            {heartbeat.name}
+          </div>
+          <div style={{
+            fontSize: 12, color: theme.textMuted, lineHeight: 1.5,
+            overflow: "hidden", textOverflow: "ellipsis",
+            display: "-webkit-box", WebkitLineClamp: 2, WebkitBoxOrient: "vertical",
+          }}>
+            {heartbeat.check_prompt}
+          </div>
+        </div>
+        <HeartbeatBadge enabled={heartbeat.enabled} />
+      </div>
+
+      <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", gap: 12 }}>
+        <div style={{ display: "flex", gap: 6, flexWrap: "wrap" }}>
+          <AgentBadge agent={heartbeat.default_agent} />
+          {tags.map((tag, idx) => <Tag key={idx}>{tag}</Tag>)}
+        </div>
+        <div style={{ display: "flex", gap: 4 }} onClick={e => e.stopPropagation()}>
+          <ActionBtn label="⚡" title="Run now" onClick={() => onAction("run", heartbeat.id)} color={theme.orange} />
+          <ActionBtn label="✎" title="Edit" onClick={() => onAction("edit", heartbeat.id)} color={theme.blue} />
+          {heartbeat.enabled ? (
+            <ActionBtn label="❚❚" title="Pause" onClick={() => onAction("pause", heartbeat.id)} color={theme.textMuted} />
+          ) : (
+            <ActionBtn label="▶" title="Resume" onClick={() => onAction("resume", heartbeat.id)} color={theme.green} />
+          )}
+          <ActionBtn label="×" title="Delete" onClick={() => onAction("delete", heartbeat.id)} color={theme.red} />
+        </div>
+      </div>
+
+      <div style={{ fontSize: 11, color: theme.textDim, marginTop: 10, fontFamily: "monospace", lineHeight: 1.6 }}>
+        Next: {heartbeat.next_run_at ? new Date(heartbeat.next_run_at).toLocaleString() : "n/a"}
+        {" · "}
+        Triggered: {heartbeat.last_triggered_at ? new Date(heartbeat.last_triggered_at).toLocaleString() : "never"}
+      </div>
+      {heartbeat.last_error && (
+        <div style={{ fontSize: 11, color: theme.red, marginTop: 6, lineHeight: 1.4 }}>
+          Last error: {heartbeat.last_error}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function HeartbeatDetailPanel({ heartbeat, ticks, onClose }) {
+  const [selectedTickId, setSelectedTickId] = useState(null);
+  const [tickOutput, setTickOutput] = useState("");
+  const [tickRunning, setTickRunning] = useState(false);
+  const outputRef = useRef(null);
+
+  useEffect(() => {
+    setSelectedTickId(ticks[0]?.id || null);
+  }, [heartbeat.id, ticks]);
+
+  useEffect(() => {
+    if (!selectedTickId) {
+      setTickOutput("");
+      setTickRunning(false);
+      return;
+    }
+    let cancelled = false;
+    const load = async () => {
+      try {
+        const data = await fetchHeartbeatTickOutput(heartbeat.id, selectedTickId);
+        if (cancelled) return;
+        setTickOutput(data.output || "");
+        setTickRunning(!!data.is_running);
+      } catch {
+        if (!cancelled) {
+          setTickOutput("");
+          setTickRunning(false);
+        }
+      }
+    };
+    load();
+    const interval = setInterval(load, 1000);
+    return () => {
+      cancelled = true;
+      clearInterval(interval);
+    };
+  }, [heartbeat.id, selectedTickId]);
+
+  useEffect(() => {
+    if (outputRef.current) {
+      outputRef.current.scrollTop = outputRef.current.scrollHeight;
+    }
+  }, [tickOutput]);
+
+  return (
+    <div style={{
+      position: "fixed", top: 0, right: 0, width: 520, height: "100vh",
+      background: theme.surface, borderLeft: `1px solid ${theme.border}`,
+      boxShadow: "-20px 0 60px rgba(0,0,0,0.4)", zIndex: 500,
+      display: "flex", flexDirection: "column",
+    }}>
+      <div style={{
+        padding: "22px 24px", borderBottom: `1px solid ${theme.border}`,
+        display: "flex", justifyContent: "space-between", alignItems: "flex-start", gap: 12,
+      }}>
+        <div>
+          <div style={{ fontSize: 18, fontWeight: 700, color: theme.text, fontFamily: "'JetBrains Mono', monospace" }}>
+            {heartbeat.name}
+          </div>
+          <div style={{ fontSize: 12, color: theme.textMuted, marginTop: 6 }}>
+            {heartbeat.working_dir}
+          </div>
+        </div>
+        <button onClick={onClose} style={{
+          background: "transparent", border: "none", color: theme.textMuted,
+          cursor: "pointer", fontSize: 22, lineHeight: 1,
+        }}>×</button>
+      </div>
+      <div style={{ padding: 24, overflow: "auto", flex: 1 }}>
+        <div style={{ display: "flex", gap: 8, flexWrap: "wrap", marginBottom: 16 }}>
+          <HeartbeatBadge enabled={heartbeat.enabled} />
+          <AgentBadge agent={heartbeat.default_agent} />
+          {heartbeat.schedule_type === "interval" ? <Tag>⟳ {heartbeat.interval_seconds}s</Tag> : <Tag>⏲ {heartbeat.cron_expr}</Tag>}
+          {heartbeat.last_decision && <Tag>{heartbeat.last_decision}</Tag>}
+        </div>
+        <div style={{ fontSize: 12, color: theme.textMuted, lineHeight: 1.7, marginBottom: 18 }}>
+          <div>Next run: {heartbeat.next_run_at ? new Date(heartbeat.next_run_at).toLocaleString() : "n/a"}</div>
+          <div>Last tick: {heartbeat.last_tick_at ? new Date(heartbeat.last_tick_at).toLocaleString() : "never"}</div>
+          <div>Last trigger: {heartbeat.last_triggered_at ? new Date(heartbeat.last_triggered_at).toLocaleString() : "never"}</div>
+          <div>Cooldown: {heartbeat.cooldown_seconds || 0}s</div>
+        </div>
+        <div style={{ marginBottom: 20 }}>
+          <div style={{ fontSize: 11, fontWeight: 700, color: theme.textMuted, letterSpacing: 0.8, textTransform: "uppercase", marginBottom: 8 }}>
+            Decision Prompt
+          </div>
+          <div style={{
+            fontSize: 12, lineHeight: 1.7, color: theme.text,
+            background: theme.bg, border: `1px solid ${theme.border}`,
+            borderRadius: 10, padding: 14, whiteSpace: "pre-wrap",
+          }}>
+            {heartbeat.check_prompt}
+          </div>
+        </div>
+        <div style={{ marginBottom: 20 }}>
+          <div style={{ fontSize: 11, fontWeight: 700, color: theme.textMuted, letterSpacing: 0.8, textTransform: "uppercase", marginBottom: 8 }}>
+            Triggered Task Template
+          </div>
+          <div style={{
+            fontSize: 12, lineHeight: 1.7, color: theme.text,
+            background: theme.bg, border: `1px solid ${theme.border}`,
+            borderRadius: 10, padding: 14, whiteSpace: "pre-wrap",
+          }}>
+            {heartbeat.action_prompt_template || "No template configured"}
+          </div>
+        </div>
+        <div>
+          <div style={{ fontSize: 11, fontWeight: 700, color: theme.textMuted, letterSpacing: 0.8, textTransform: "uppercase", marginBottom: 8 }}>
+            Recent Ticks
+          </div>
+          <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+            {ticks.map((tick) => {
+              let payload = null;
+              try { payload = tick.decision_payload ? JSON.parse(tick.decision_payload) : null; } catch {}
+              return (
+                <div key={tick.id} style={{
+                  background: theme.bg, border: `1px solid ${theme.border}`,
+                  borderRadius: 10, padding: 12, cursor: "pointer",
+                  boxShadow: selectedTickId === tick.id ? `0 0 0 1px ${theme.accent} inset` : "none",
+                }}>
+                  <div onClick={() => setSelectedTickId(tick.id)} style={{ display: "flex", justifyContent: "space-between", gap: 8, marginBottom: 6 }}>
+                    <div style={{ fontSize: 12, fontWeight: 600, color: theme.text }}>{tick.decision_type || tick.status}</div>
+                    <div style={{ fontSize: 11, color: theme.textDim, fontFamily: "monospace" }}>
+                      {tick.started_at ? new Date(tick.started_at).toLocaleString() : ""}
+                    </div>
+                  </div>
+                  {payload?.reason && (
+                    <div style={{ fontSize: 12, color: theme.textMuted, lineHeight: 1.5 }}>
+                      {payload.reason}
+                    </div>
+                  )}
+                  {tick.error && (
+                    <div style={{ fontSize: 12, color: theme.red, lineHeight: 1.5 }}>
+                      {tick.error}
+                    </div>
+                  )}
+                  {tick.task_id && (
+                    <div style={{ fontSize: 11, color: theme.accent, marginTop: 6, fontFamily: "monospace" }}>
+                      Triggered task #{tick.task_id}
+                    </div>
+                  )}
+                </div>
+              );
+            })}
+            {ticks.length === 0 && (
+              <div style={{
+                border: `1px dashed ${theme.border}`, borderRadius: 10,
+                padding: 24, textAlign: "center", color: theme.textDim, fontSize: 12,
+              }}>
+                No ticks yet
+              </div>
+            )}
+          </div>
+        </div>
+        <div style={{ marginTop: 20 }}>
+          <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: 8 }}>
+            <div style={{ fontSize: 11, fontWeight: 700, color: theme.textMuted, letterSpacing: 0.8, textTransform: "uppercase" }}>
+              Tick Log
+            </div>
+            {selectedTickId && (
+              <div style={{ fontSize: 11, color: tickRunning ? theme.orange : theme.textDim, fontFamily: "monospace" }}>
+                {tickRunning ? "LIVE" : "Stored"} · tick #{selectedTickId}
+              </div>
+            )}
+          </div>
+          <div
+            ref={outputRef}
+            style={{
+              background: theme.bg, border: `1px solid ${theme.border}`,
+              borderRadius: 10, padding: 14, minHeight: 180, maxHeight: 320,
+              overflow: "auto", fontFamily: "'JetBrains Mono', monospace",
+              fontSize: 12, lineHeight: 1.6, whiteSpace: "pre-wrap",
+              color: theme.text,
+            }}
+          >
+            {selectedTickId ? (tickOutput || "No output captured for this tick.") : "Select a tick to view its log."}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
 function NewTaskModal({ onClose, onSubmit, initialData, mode = "create" }) {
   const savedDir = localStorage.getItem("agentforge_working_dir") || "~/papers";
   const [form, setForm] = useState(() => {
@@ -2037,9 +2532,14 @@ function SettingsModal({ onClose, timeout: initialTimeout, defaultAgent: initial
 
 export default function App() {
   const [tasks, setTasks] = useState([]);
+  const [heartbeats, setHeartbeats] = useState([]);
+  const [heartbeatTicks, setHeartbeatTicks] = useState([]);
+  const [activeView, setActiveView] = useState("tasks");
   const [showNew, setShowNew] = useState(false);
+  const [showNewHeartbeat, setShowNewHeartbeat] = useState(false);
   const [showSettings, setShowSettings] = useState(false);
   const [detail, setDetail] = useState(null);
+  const [heartbeatDetail, setHeartbeatDetail] = useState(null);
   const [connected, setConnected] = useState(false);
   const [filter, setFilter] = useState("");
   const [taskTimeout, setTaskTimeout] = useState(600);
@@ -2051,6 +2551,7 @@ export default function App() {
   const [apiError, setApiError] = useState(null);
   const [editingTask, setEditingTask] = useState(null);
   const [forkingTask, setForkingTask] = useState(null);
+  const [editingHeartbeat, setEditingHeartbeat] = useState(null);
 
   // ─── Color mode ───
   const [colorMode, setColorMode] = useState(() =>
@@ -2095,8 +2596,9 @@ export default function App() {
 
   const poll = useCallback(async () => {
     try {
-      const data = await fetchTasks();
-      setTasks(data);
+      const [taskData, heartbeatData] = await Promise.all([fetchTasks(), fetchHeartbeats()]);
+      setTasks(taskData);
+      setHeartbeats(heartbeatData);
       setConnected(true);
       setApiError(null);
     } catch (err) {
@@ -2144,6 +2646,39 @@ export default function App() {
     }
   };
 
+  const handleHeartbeatAction = async (action, id) => {
+    try {
+      if (action === "run") {
+        await runHeartbeatNow(id);
+      } else if (action === "pause") {
+        await pauseHeartbeat(id);
+      } else if (action === "resume") {
+        await resumeHeartbeatApi(id);
+      } else if (action === "delete") {
+        await deleteHeartbeat(id);
+        if (heartbeatDetail?.id === id) {
+          setHeartbeatDetail(null);
+          setHeartbeatTicks([]);
+        }
+      } else if (action === "edit") {
+        const heartbeat = heartbeats.find(h => h.id === id);
+        if (heartbeat) setEditingHeartbeat(heartbeat);
+        return;
+      }
+      poll();
+      if (heartbeatDetail?.id === id && action !== "delete") {
+        const [updatedHeartbeat, ticks] = await Promise.all([
+          fetch(`${API}/heartbeats/${id}`).then(r => r.json()),
+          fetchHeartbeatTicks(id),
+        ]);
+        setHeartbeatDetail(updatedHeartbeat);
+        setHeartbeatTicks(ticks);
+      }
+    } catch (e) {
+      setApiError(`Heartbeat ${action} failed: ${e.message}`);
+    }
+  };
+
   const handleCreate = async (data) => {
     try {
       await createTask(data);
@@ -2187,6 +2722,37 @@ export default function App() {
     poll();
   };
 
+  const handleCreateHeartbeat = async (data) => {
+    try {
+      await createHeartbeat(data);
+      setShowNewHeartbeat(false);
+      poll();
+    } catch (e) {
+      setApiError(`Create heartbeat failed: ${e.message}`);
+    }
+  };
+
+  const handleEditHeartbeat = async (data) => {
+    try {
+      await updateHeartbeat(editingHeartbeat.id, data);
+      setEditingHeartbeat(null);
+      poll();
+    } catch (e) {
+      setApiError(`Edit heartbeat failed: ${e.message}`);
+    }
+  };
+
+  const openHeartbeatDetail = async (heartbeat) => {
+    setHeartbeatDetail(heartbeat);
+    try {
+      const ticks = await fetchHeartbeatTicks(heartbeat.id);
+      setHeartbeatTicks(ticks);
+    } catch (e) {
+      setApiError(`Failed to fetch heartbeat ticks: ${e.message}`);
+      setHeartbeatTicks([]);
+    }
+  };
+
   const filtered = filter
     ? tasks.filter(t =>
         t.title.toLowerCase().includes(filter.toLowerCase()) ||
@@ -2196,6 +2762,7 @@ export default function App() {
 
   const runningCount = tasks.filter(t => t.status === "running").length;
   const scheduledCount = tasks.filter(t => t.status === "scheduled").length;
+  const enabledHeartbeatCount = heartbeats.filter(h => h.enabled).length;
 
   if (backendError) {
     return (
@@ -2292,14 +2859,36 @@ export default function App() {
               ) : (
                 <span style={{ color: theme.red }}>● Disconnected — run `python taskboard.py`</span>
               )}
-              {connected && ` · ${runningCount} running · ${scheduledCount} scheduled`}
+              {connected && ` · ${runningCount} running · ${scheduledCount} scheduled · ${enabledHeartbeatCount} heartbeats`}
             </div>
           </div>
         </div>
 
         <div style={{ display: "flex", alignItems: "center", gap: 10 }}>
+          <div style={{
+            display: "flex", background: theme.surface, border: `1px solid ${theme.border}`,
+            borderRadius: 10, padding: 4, gap: 4,
+          }}>
+            {[
+              { key: "tasks", label: "Tasks" },
+              { key: "heartbeats", label: "Heartbeats" },
+            ].map(tab => (
+              <button
+                key={tab.key}
+                onClick={() => setActiveView(tab.key)}
+                style={{
+                  padding: "6px 10px", borderRadius: 8, border: "none",
+                  background: activeView === tab.key ? theme.accentGlow : "transparent",
+                  color: activeView === tab.key ? theme.accent : theme.textMuted,
+                  cursor: "pointer", fontSize: 12, fontWeight: 700,
+                }}
+              >
+                {tab.label}
+              </button>
+            ))}
+          </div>
           <input
-            placeholder="Filter tasks..."
+            placeholder={activeView === "tasks" ? "Filter tasks..." : "Filter heartbeats..."}
             value={filter}
             onChange={e => setFilter(e.target.value)}
             style={{
@@ -2339,7 +2928,7 @@ export default function App() {
             ⚙
           </button>
           </Tooltip>
-          <button onClick={() => setShowNew(true)} style={{
+          <button onClick={() => activeView === "tasks" ? setShowNew(true) : setShowNewHeartbeat(true)} style={{
             padding: "8px 18px", borderRadius: 8, border: "none",
             background: theme.accent, color: "#fff", cursor: "pointer",
             fontSize: 12, fontWeight: 700, letterSpacing: 0.3,
@@ -2347,29 +2936,69 @@ export default function App() {
             boxShadow: `0 0 24px ${theme.accentGlow}`,
             transition: "transform 0.15s",
           }}>
-            + New Task
+            {activeView === "tasks" ? "+ New Task" : "+ New Heartbeat"}
           </button>
         </div>
       </div>
 
-      {/* Kanban Board */}
-      <div style={{
-        display: "flex", gap: 20, padding: 28,
-        minHeight: "calc(100vh - 72px)",
-      }}>
-        {COLUMNS.map(col => (
-          <Column
-            key={col.key}
-            col={col}
-            tasks={filtered.filter(t => col.statuses.includes(t.status))}
-            onAction={handleAction}
-            onViewDetail={setDetail}
-          />
-        ))}
-      </div>
+      {activeView === "tasks" ? (
+        <div style={{
+          display: "flex", gap: 20, padding: 28,
+          minHeight: "calc(100vh - 72px)",
+        }}>
+          {COLUMNS.map(col => (
+            <Column
+              key={col.key}
+              col={col}
+              tasks={filtered.filter(t => col.statuses.includes(t.status))}
+              onAction={handleAction}
+              onViewDetail={setDetail}
+            />
+          ))}
+        </div>
+      ) : (
+        <div style={{ padding: 28, minHeight: "calc(100vh - 72px)" }}>
+          <div style={{
+            display: "grid",
+            gridTemplateColumns: "repeat(auto-fit, minmax(360px, 1fr))",
+            gap: 14,
+          }}>
+            {(filter
+              ? heartbeats.filter(h =>
+                  h.name.toLowerCase().includes(filter.toLowerCase()) ||
+                  h.check_prompt.toLowerCase().includes(filter.toLowerCase())
+                )
+              : heartbeats
+            ).map(h => (
+              <HeartbeatCard
+                key={h.id}
+                heartbeat={h}
+                onAction={handleHeartbeatAction}
+                onViewDetail={openHeartbeatDetail}
+              />
+            ))}
+            {heartbeats.length === 0 && (
+              <div style={{
+                border: `1px dashed ${theme.border}`, borderRadius: 12,
+                padding: 32, textAlign: "center", color: theme.textDim, fontSize: 12,
+                gridColumn: "1 / -1",
+              }}>
+                No heartbeats yet
+              </div>
+            )}
+          </div>
+        </div>
+      )}
 
       {/* Modals */}
       {showNew && <NewTaskModal onClose={() => setShowNew(false)} onSubmit={handleCreate} initialData={{ agent: defaultAgent }} />}
+      {showNewHeartbeat && (
+        <HeartbeatModal
+          onClose={() => setShowNewHeartbeat(false)}
+          onSubmit={handleCreateHeartbeat}
+          defaultAgent={defaultAgent}
+        />
+      )}
       {editingTask && (
         <NewTaskModal
           onClose={() => setEditingTask(null)}
@@ -2378,6 +3007,15 @@ export default function App() {
           mode="edit"
         />
       )}
+      {editingHeartbeat && (
+        <HeartbeatModal
+          onClose={() => setEditingHeartbeat(null)}
+          onSubmit={handleEditHeartbeat}
+          initialData={editingHeartbeat}
+          defaultAgent={defaultAgent}
+          mode="edit"
+        />
+      )}
       {forkingTask && (
         <NewTaskModal
           onClose={() => setForkingTask(null)}
@@ -2399,9 +3037,16 @@ export default function App() {
         />
       )}
       {detail && <DetailPanel task={tasks.find(t => t.id === detail.id) || detail} onClose={() => setDetail(null)} onRespond={handleRespond} onResume={handleResume} />}
+      {heartbeatDetail && (
+        <HeartbeatDetailPanel
+          heartbeat={heartbeats.find(h => h.id === heartbeatDetail.id) || heartbeatDetail}
+          ticks={heartbeatTicks}
+          onClose={() => { setHeartbeatDetail(null); setHeartbeatTicks([]); }}
+        />
+      )}
 
       {/* Startup guide when no tasks */}
-      {connected && tasks.length === 0 && (
+      {connected && activeView === "tasks" && tasks.length === 0 && (
         <div style={{
           position: "fixed", bottom: 28, left: "50%", transform: "translateX(-50%)",
           background: theme.surface, border: `1px solid ${theme.border}`,
@@ -2417,6 +3062,21 @@ export default function App() {
           </div>
         </div>
       )}
+      {connected && activeView === "heartbeats" && heartbeats.length === 0 && (
+        <div style={{
+          position: "fixed", bottom: 28, left: "50%", transform: "translateX(-50%)",
+          background: theme.surface, border: `1px solid ${theme.border}`,
+          borderRadius: 12, padding: "16px 24px", maxWidth: 560,
+          boxShadow: "0 8px 32px rgba(0,0,0,0.3)",
+        }}>
+          <div style={{ fontSize: 13, color: theme.text, fontWeight: 600, marginBottom: 6 }}>
+            Heartbeats let AgentForge check first and only create work when needed.
+          </div>
+          <div style={{ fontSize: 11, color: theme.textDim, lineHeight: 1.6 }}>
+            Create one to run a stateless agent decision tick on an interval or cron schedule, then trigger a real task only when the signal is actionable.
+          </div>
+        </div>
+      )}
 
       {!connected && (
         <div style={{
diff --git a/taskboard.py b/taskboard.py
index 7cb725a..86667cd 100644
--- a/taskboard.py
+++ b/taskboard.py
@@ -101,6 +101,19 @@ class ScheduleType(str, Enum):
     CRON = "cron"            # recurring cron expression
 
 
+class HeartbeatScheduleType(str, Enum):
+    CRON = "cron"
+    INTERVAL = "interval"
+
+
+class HeartbeatDecisionType(str, Enum):
+    IDLE = "idle"
+    TRIGGER_TASK = "trigger_task"
+    RESUME_TASK = "resume_task"
+    NOTIFY_ONLY = "notify_only"
+    ERROR = "error"
+
+
 @dataclass
 class Task:
     id: Optional[int] = None
@@ -130,6 +143,29 @@ class Task:
     feishu_root_msg_id: Optional[str] = None  # Feishu root message_id that created this task
 
 
+@dataclass
+class Heartbeat:
+    id: Optional[int] = None
+    name: str = ""
+    enabled: bool = True
+    working_dir: str = "."
+    schedule_type: HeartbeatScheduleType = HeartbeatScheduleType.INTERVAL
+    cron_expr: Optional[str] = None
+    interval_seconds: Optional[int] = None
+    check_prompt: str = ""
+    action_prompt_template: str = ""
+    default_agent: str = "claude"
+    cooldown_seconds: int = 0
+    next_run_at: Optional[str] = None
+    last_tick_at: Optional[str] = None
+    last_decision: Optional[str] = None
+    last_error: Optional[str] = None
+    last_triggered_at: Optional[str] = None
+    last_dedupe_key: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
 # ──────────────────────────── Database ────────────────────────────
 
 class TaskDB:
@@ -235,6 +271,75 @@ def _init_db(self):
         except sqlite3.OperationalError:
             pass  # Column already exists
 
+        self.conn.execute("""
+            CREATE TABLE IF NOT EXISTS heartbeats (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                name TEXT NOT NULL,
+                enabled INTEGER NOT NULL DEFAULT 1,
+                working_dir TEXT DEFAULT '.',
+                schedule_type TEXT NOT NULL,
+                cron_expr TEXT,
+                interval_seconds INTEGER,
+                check_prompt TEXT NOT NULL,
+                action_prompt_template TEXT DEFAULT '',
+                default_agent TEXT DEFAULT 'claude',
+                cooldown_seconds INTEGER DEFAULT 0,
+                next_run_at TEXT,
+                last_tick_at TEXT,
+                last_decision TEXT,
+                last_error TEXT,
+                last_triggered_at TEXT,
+                last_dedupe_key TEXT,
+                created_at TEXT DEFAULT (datetime('now')),
+                updated_at TEXT DEFAULT (datetime('now'))
+            )
+        """)
+        self.conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_heartbeats_next_run
+            ON heartbeats(enabled, next_run_at)
+        """)
+        self.conn.execute("""
+            CREATE TABLE IF NOT EXISTS heartbeat_ticks (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                heartbeat_id INTEGER NOT NULL,
+                started_at TEXT NOT NULL,
+                finished_at TEXT,
+                status TEXT NOT NULL,
+                decision_type TEXT,
+                decision_payload TEXT,
+                task_id INTEGER,
+                raw_output TEXT,
+                error TEXT,
+                FOREIGN KEY (heartbeat_id) REFERENCES heartbeats(id),
+                FOREIGN KEY (task_id) REFERENCES tasks(id)
+            )
+        """)
+        self.conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_heartbeat_ticks_heartbeat_id
+            ON heartbeat_ticks(heartbeat_id, started_at DESC)
+        """)
+        try:
+            self.conn.execute("ALTER TABLE heartbeat_ticks ADD COLUMN raw_output TEXT")
+            self.conn.commit()
+        except sqlite3.OperationalError:
+            pass  # Column already exists
+        self.conn.execute("""
+            CREATE TABLE IF NOT EXISTS heartbeat_dedup (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                heartbeat_id INTEGER NOT NULL,
+                dedupe_key TEXT NOT NULL,
+                task_id INTEGER,
+                triggered_at TEXT NOT NULL,
+                FOREIGN KEY (heartbeat_id) REFERENCES heartbeats(id),
+                FOREIGN KEY (task_id) REFERENCES tasks(id),
+                UNIQUE(heartbeat_id, dedupe_key)
+            )
+        """)
+        self.conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_heartbeat_dedup_heartbeat_id
+            ON heartbeat_dedup(heartbeat_id, triggered_at DESC)
+        """)
+
         # Create task_output_events table for structured output recording
         self.conn.execute("""
             CREATE TABLE IF NOT EXISTS task_output_events (
@@ -379,6 +484,182 @@ def set_setting(self, key: str, value: str):
                 (key, value))
             self.conn.commit()
 
+    def _deserialize_heartbeat(self, row) -> dict:
+        d = dict(row)
+        d["enabled"] = bool(d.get("enabled"))
+        return d
+
+    def _compute_heartbeat_next_run_at(self, heartbeat: Heartbeat, now: Optional[datetime] = None) -> str:
+        now = now or datetime.now()
+        if heartbeat.schedule_type == HeartbeatScheduleType.CRON:
+            if not heartbeat.cron_expr:
+                raise ValueError("cron heartbeat requires cron_expr")
+            return croniter(heartbeat.cron_expr, now).get_next(datetime).isoformat()
+        if heartbeat.schedule_type == HeartbeatScheduleType.INTERVAL:
+            if not heartbeat.interval_seconds or heartbeat.interval_seconds <= 0:
+                raise ValueError("interval heartbeat requires interval_seconds > 0")
+            return (now + timedelta(seconds=int(heartbeat.interval_seconds))).isoformat()
+        raise ValueError(f"Unsupported heartbeat schedule_type: {heartbeat.schedule_type}")
+
+    def add_heartbeat(self, heartbeat: Heartbeat) -> int:
+        with self.lock:
+            now = datetime.now().isoformat()
+            if heartbeat.next_run_at is None:
+                heartbeat.next_run_at = self._compute_heartbeat_next_run_at(heartbeat, datetime.now())
+            cur = self.conn.execute("""
+                INSERT INTO heartbeats (
+                    name, enabled, working_dir, schedule_type, cron_expr,
+                    interval_seconds, check_prompt, action_prompt_template,
+                    default_agent, cooldown_seconds, next_run_at, last_tick_at,
+                    last_decision, last_error, last_triggered_at, last_dedupe_key,
+                    created_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """, (
+                heartbeat.name,
+                1 if heartbeat.enabled else 0,
+                heartbeat.working_dir,
+                heartbeat.schedule_type.value,
+                heartbeat.cron_expr,
+                heartbeat.interval_seconds,
+                heartbeat.check_prompt,
+                heartbeat.action_prompt_template,
+                heartbeat.default_agent,
+                heartbeat.cooldown_seconds,
+                heartbeat.next_run_at,
+                heartbeat.last_tick_at,
+                heartbeat.last_decision,
+                heartbeat.last_error,
+                heartbeat.last_triggered_at,
+                heartbeat.last_dedupe_key,
+                now,
+                now,
+            ))
+            self.conn.commit()
+            return cur.lastrowid
+
+    ALLOWED_HEARTBEAT_COLUMNS = frozenset({
+        "name", "enabled", "working_dir", "schedule_type", "cron_expr",
+        "interval_seconds", "check_prompt", "action_prompt_template",
+        "default_agent", "cooldown_seconds", "next_run_at", "last_tick_at",
+        "last_decision", "last_error", "last_triggered_at", "last_dedupe_key",
+        "updated_at",
+    })
+
+    def update_heartbeat(self, heartbeat_id: int, **kwargs):
+        invalid = set(kwargs) - self.ALLOWED_HEARTBEAT_COLUMNS
+        if invalid:
+            raise ValueError(f"Invalid heartbeat column(s): {invalid}")
+        with self.lock:
+            kwargs["updated_at"] = datetime.now().isoformat()
+            sets = ", ".join(f"{k} = ?" for k in kwargs)
+            vals = list(kwargs.values()) + [heartbeat_id]
+            self.conn.execute(f"UPDATE heartbeats SET {sets} WHERE id = ?", vals)
+            self.conn.commit()
+
+    def get_heartbeat(self, heartbeat_id: int) -> Optional[dict]:
+        with self.lock:
+            row = self.conn.execute("SELECT * FROM heartbeats WHERE id = ?", (heartbeat_id,)).fetchone()
+            return self._deserialize_heartbeat(row) if row else None
+
+    def get_all_heartbeats(self) -> list[dict]:
+        with self.lock:
+            rows = self.conn.execute("SELECT * FROM heartbeats ORDER BY created_at DESC").fetchall()
+            return [self._deserialize_heartbeat(r) for r in rows]
+
+    def get_due_heartbeats(self) -> list[dict]:
+        now = datetime.now().isoformat()
+        with self.lock:
+            rows = self.conn.execute("""
+                SELECT * FROM heartbeats
+                WHERE enabled = 1
+                  AND next_run_at IS NOT NULL
+                  AND next_run_at <= ?
+            """, (now,)).fetchall()
+            return [self._deserialize_heartbeat(r) for r in rows]
+
+    def delete_heartbeat(self, heartbeat_id: int):
+        with self.transaction():
+            self.conn.execute("DELETE FROM heartbeat_ticks WHERE heartbeat_id = ?", (heartbeat_id,))
+            self.conn.execute("DELETE FROM heartbeat_dedup WHERE heartbeat_id = ?", (heartbeat_id,))
+            self.conn.execute("DELETE FROM heartbeats WHERE id = ?", (heartbeat_id,))
+
+    def add_heartbeat_tick(self, heartbeat_id: int) -> int:
+        with self.lock:
+            cur = self.conn.execute("""
+                INSERT INTO heartbeat_ticks (heartbeat_id, started_at, status)
+                VALUES (?, ?, 'running')
+            """, (heartbeat_id, datetime.now().isoformat()))
+            self.conn.commit()
+            return cur.lastrowid
+
+    def finish_heartbeat_tick(self, tick_id: int, status: str, decision_type: Optional[str] = None,
+                              decision_payload: Optional[dict] = None, task_id: Optional[int] = None,
+                              raw_output: Optional[str] = None, error: Optional[str] = None):
+        payload_json = json.dumps(decision_payload, ensure_ascii=False) if decision_payload is not None else None
+        with self.lock:
+            self.conn.execute("""
+                UPDATE heartbeat_ticks
+                SET finished_at = ?, status = ?, decision_type = ?, decision_payload = ?, task_id = ?, raw_output = ?, error = ?
+                WHERE id = ?
+            """, (
+                datetime.now().isoformat(),
+                status,
+                decision_type,
+                payload_json,
+                task_id,
+                raw_output,
+                error,
+                tick_id,
+            ))
+            self.conn.commit()
+
+    def get_heartbeat_ticks(self, heartbeat_id: int, limit: int = 50) -> list[dict]:
+        with self.lock:
+            rows = self.conn.execute("""
+                SELECT * FROM heartbeat_ticks
+                WHERE heartbeat_id = ?
+                ORDER BY started_at DESC
+                LIMIT ?
+            """, (heartbeat_id, limit)).fetchall()
+            return [dict(r) for r in rows]
+
+    def get_heartbeat_tick(self, heartbeat_id: int, tick_id: int) -> Optional[dict]:
+        with self.lock:
+            row = self.conn.execute("""
+                SELECT * FROM heartbeat_ticks
+                WHERE heartbeat_id = ? AND id = ?
+            """, (heartbeat_id, tick_id)).fetchone()
+            return dict(row) if row else None
+
+    def get_latest_heartbeat_tick(self, heartbeat_id: int) -> Optional[dict]:
+        with self.lock:
+            row = self.conn.execute("""
+                SELECT * FROM heartbeat_ticks
+                WHERE heartbeat_id = ?
+                ORDER BY started_at DESC
+                LIMIT 1
+            """, (heartbeat_id,)).fetchone()
+            return dict(row) if row else None
+
+    def get_heartbeat_dedup(self, heartbeat_id: int, dedupe_key: str) -> Optional[dict]:
+        with self.lock:
+            row = self.conn.execute("""
+                SELECT * FROM heartbeat_dedup
+                WHERE heartbeat_id = ? AND dedupe_key = ?
+            """, (heartbeat_id, dedupe_key)).fetchone()
+            return dict(row) if row else None
+
+    def upsert_heartbeat_dedup(self, heartbeat_id: int, dedupe_key: str, task_id: Optional[int]):
+        with self.lock:
+            now = datetime.now().isoformat()
+            self.conn.execute("""
+                INSERT INTO heartbeat_dedup (heartbeat_id, dedupe_key, task_id, triggered_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(heartbeat_id, dedupe_key)
+                DO UPDATE SET task_id = excluded.task_id, triggered_at = excluded.triggered_at
+            """, (heartbeat_id, dedupe_key, task_id, now))
+            self.conn.commit()
+
     ALLOWED_TASK_COLUMNS = frozenset({
         "title", "prompt", "working_dir", "status", "schedule_type",
         "cron_expr", "delay_seconds", "next_run_at", "last_run_at",
@@ -659,7 +940,9 @@ def __init__(self, db: TaskDB, on_task_update: Optional[Callable] = None,
         self._shutting_down = False
         self._thread: Optional[threading.Thread] = None
         self._active_tasks: dict[int, threading.Thread] = {}
+        self._active_heartbeats: dict[int, threading.Thread] = {}
         self._live_output: dict[int, str] = {}  # task_id -> accumulated stdout
+        self._live_heartbeat_output: dict[int, str] = {}  # tick_id -> accumulated stdout/stderr
         self._active_pgids: dict[int, int] = {}  # task_id -> process group id
 
     def start(self):
@@ -681,6 +964,12 @@ def stop(self):
             for tid, t in running.items():
                 remaining = max(0, deadline - time.time())
                 t.join(timeout=remaining)
+        heartbeat_running = {hid: t for hid, t in self._active_heartbeats.items() if t.is_alive()}
+        if heartbeat_running:
+            logger.info(f"Waiting for {len(heartbeat_running)} heartbeat(s) to finish...")
+            for hid, t in heartbeat_running.items():
+                remaining = max(0, deadline - time.time())
+                t.join(timeout=remaining)
         # Gracefully terminate any processes still alive, then force-kill if needed
         for tid, pgid in list(self._active_pgids.items()):
             try:
@@ -738,6 +1027,12 @@ def _tick(self):
                 nra = task.get("next_run_at")
                 if nra and datetime.fromisoformat(nra) <= datetime.now():
                     self._spawn_task(task)
+        due_heartbeats = self.db.get_due_heartbeats()
+        for heartbeat in due_heartbeats:
+            hid = heartbeat["id"]
+            if hid in self._active_heartbeats and self._active_heartbeats[hid].is_alive():
+                continue
+            self._spawn_heartbeat(heartbeat)
 
     def _schedule_delayed(self, task: dict):
         delay = task.get("delay_seconds", 0) or 0
@@ -747,6 +1042,11 @@ def _schedule_delayed(self, task: dict):
                             next_run_at=run_at.isoformat())
         self._notify(task["id"])
 
+    def _spawn_heartbeat(self, heartbeat: dict):
+        t = threading.Thread(target=self._execute_heartbeat, args=(heartbeat,), daemon=True)
+        self._active_heartbeats[heartbeat["id"]] = t
+        t.start()
+
     def _spawn_task(self, task: dict):
         # Register the thread in _active_tasks *before* updating the DB so
         # that if the thread crashes immediately after the DB write, the task
@@ -756,6 +1056,328 @@ def _spawn_task(self, task: dict):
         self.db.update_task(task["id"], status="running")
         t.start()
 
+    def _render_heartbeat_check_prompt(self, heartbeat: dict) -> str:
+        lines = [
+            "You are AgentForge heartbeat decision engine.",
+            "Return JSON only. No markdown, no explanation, no code fences.",
+            "JSON schema:",
+            '{"decision":"idle|trigger_task|error","reason":"string","dedupe_key":"string","title":"string","prompt":"string","metadata":{}}',
+            "",
+            f"Heartbeat name: {heartbeat['name']}",
+            f"Working directory: {heartbeat['working_dir']}",
+            f"Current time: {datetime.now().isoformat()}",
+            f"Last tick at: {heartbeat.get('last_tick_at') or ''}",
+            f"Last decision: {heartbeat.get('last_decision') or ''}",
+            f"Last triggered at: {heartbeat.get('last_triggered_at') or ''}",
+            f"Last dedupe key: {heartbeat.get('last_dedupe_key') or ''}",
+            "",
+            "User-defined check instructions:",
+            heartbeat["check_prompt"],
+        ]
+        if heartbeat.get("action_prompt_template"):
+            lines.extend([
+                "",
+                "When decision is trigger_task, use this action prompt template as the base prompt to expand or adapt:",
+                heartbeat["action_prompt_template"],
+            ])
+        return "\n".join(lines)
+
+    def _parse_heartbeat_decision(self, raw_text: str) -> dict:
+        text = raw_text.strip()
+        if text.startswith("```"):
+            lines = [line for line in text.splitlines() if not line.strip().startswith("```")]
+            text = "\n".join(lines).strip()
+        if not text.startswith("{"):
+            start = text.find("{")
+            end = text.rfind("}")
+            if start != -1 and end != -1 and end > start:
+                text = text[start:end + 1]
+        payload = json.loads(text)
+        decision = payload.get("decision")
+        if decision not in {d.value for d in HeartbeatDecisionType}:
+            raise ValueError(f"Invalid heartbeat decision: {decision}")
+        normalized = {
+            "decision": decision,
+            "reason": str(payload.get("reason", "")),
+            "dedupe_key": str(payload.get("dedupe_key", "")),
+            "title": str(payload.get("title", "")),
+            "prompt": str(payload.get("prompt", "")),
+            "metadata": payload.get("metadata", {}) or {},
+        }
+        if not isinstance(normalized["metadata"], dict):
+            raise ValueError("Heartbeat decision metadata must be an object")
+        return normalized
+
+    def _run_agent_prompt_once(self, agent: str, prompt: str, working_dir: str) -> tuple[bool, str]:
+        working_dir_expanded = os.path.expanduser(working_dir)
+        if agent == "codex":
+            cmd = [
+                "codex", "exec",
+                "--json",
+                "--dangerously-bypass-approvals-and-sandbox",
+                "--skip-git-repo-check",
+                "--cd", working_dir_expanded,
+                prompt,
+            ]
+        else:
+            cmd = [
+                "claude", "-p", prompt,
+                "--output-format", "stream-json",
+                "--verbose",
+                "--permission-mode", "bypassPermissions",
+            ]
+        return self._run_agent_command(agent, cmd, working_dir_expanded)
+
+    def _run_agent_command(self, agent: str, cmd: list[str], working_dir_expanded: str,
+                           on_stdout_line: Optional[Callable[[str], None]] = None,
+                           on_stderr_line: Optional[Callable[[str], None]] = None) -> tuple[bool, str]:
+        try:
+            proc = subprocess.Popen(
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                cwd=working_dir_expanded,
+                env=_get_env(),
+            )
+        except FileNotFoundError:
+            return False, f"{agent} CLI not found"
+        except OSError as e:
+            return False, str(e)
+        timeout_secs = int(self.db.get_setting("timeout", "600"))
+        stdout_chunks = []
+        stderr_chunks = []
+
+        def _read_stream(stream, chunks, callback):
+            for line in stream:
+                chunks.append(line)
+                if callback:
+                    callback(line)
+
+        stdout_thread = threading.Thread(
+            target=_read_stream,
+            args=(proc.stdout, stdout_chunks, on_stdout_line),
+            daemon=True,
+        )
+        stderr_thread = threading.Thread(
+            target=_read_stream,
+            args=(proc.stderr, stderr_chunks, on_stderr_line),
+            daemon=True,
+        )
+        stdout_thread.start()
+        stderr_thread.start()
+        try:
+            proc.wait(timeout=timeout_secs)
+        except subprocess.TimeoutExpired:
+            try:
+                proc.kill()
+            except OSError:
+                pass
+            stdout_thread.join(timeout=1)
+            stderr_thread.join(timeout=1)
+            return False, f"{agent} heartbeat decision timed out"
+
+        stdout_thread.join(timeout=1)
+        stderr_thread.join(timeout=1)
+        raw_stdout = "".join(stdout_chunks)
+        raw_stderr = "".join(stderr_chunks)
+        if proc.returncode != 0:
+            return False, raw_stderr or raw_stdout or f"{agent} heartbeat decision failed"
+
+        if agent == "codex":
+            out = ""
+            for line in raw_stdout.splitlines():
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    event = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if (event.get("type") == "item.completed"
+                        and event.get("item", {}).get("type") == "agent_message"):
+                    out = event["item"].get("text", "")
+            return True, out or raw_stdout
+
+        out = ""
+        last_assistant_text = ""
+        for line in raw_stdout.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if event.get("type") == "assistant":
+                msg = event.get("message", {})
+                content = msg.get("content", [])
+                text_parts = []
+                for c in content:
+                    if isinstance(c, str):
+                        text_parts.append(c)
+                    elif isinstance(c, dict) and c.get("type") == "text":
+                        text_parts.append(c.get("text", ""))
+                if text_parts:
+                    last_assistant_text = "".join(text_parts)
+            elif event.get("type") == "result":
+                result_text = event.get("result")
+                if result_text:
+                    out = result_text
+        return True, out or last_assistant_text or raw_stdout
+
+    def _heartbeat_trigger_suppressed(self, heartbeat: dict, dedupe_key: str) -> bool:
+        if not dedupe_key:
+            return False
+        existing = self.db.get_heartbeat_dedup(heartbeat["id"], dedupe_key)
+        if not existing:
+            return False
+        cooldown = int(heartbeat.get("cooldown_seconds") or 0)
+        triggered_at = existing.get("triggered_at")
+        if triggered_at:
+            try:
+                triggered_dt = datetime.fromisoformat(triggered_at)
+                if cooldown > 0 and datetime.now() < triggered_dt + timedelta(seconds=cooldown):
+                    return True
+            except ValueError:
+                pass
+        existing_task_id = existing.get("task_id")
+        if existing_task_id:
+            task = self.db.get_task(existing_task_id)
+            if task and task.get("status") in ("pending", "scheduled", "blocked", "running"):
+                return True
+        return False
+
+    def _execute_heartbeat(self, heartbeat: dict):
+        hid = heartbeat["id"]
+        tick_id = self.db.add_heartbeat_tick(hid)
+        now = datetime.now()
+        output_chunks: list[str] = []
+        self._live_heartbeat_output[tick_id] = ""
+        next_run_at = self.db._compute_heartbeat_next_run_at(
+            Heartbeat(
+                id=hid,
+                name=heartbeat["name"],
+                enabled=heartbeat["enabled"],
+                working_dir=heartbeat["working_dir"],
+                schedule_type=HeartbeatScheduleType(heartbeat["schedule_type"]),
+                cron_expr=heartbeat.get("cron_expr"),
+                interval_seconds=heartbeat.get("interval_seconds"),
+                check_prompt=heartbeat["check_prompt"],
+                action_prompt_template=heartbeat.get("action_prompt_template") or "",
+                default_agent=heartbeat.get("default_agent") or "claude",
+                cooldown_seconds=int(heartbeat.get("cooldown_seconds") or 0),
+            ),
+            now,
+        )
+        try:
+            def _append_tick_output(line: str):
+                output_chunks.append(line)
+                self._live_heartbeat_output[tick_id] = "".join(output_chunks)
+
+            agent = heartbeat.get("default_agent") or "claude"
+            prompt = self._render_heartbeat_check_prompt(heartbeat)
+            working_dir_expanded = os.path.expanduser(heartbeat["working_dir"])
+            if agent == "codex":
+                cmd = [
+                    "codex", "exec",
+                    "--json",
+                    "--dangerously-bypass-approvals-and-sandbox",
+                    "--skip-git-repo-check",
+                    "--cd", working_dir_expanded,
+                    prompt,
+                ]
+            else:
+                cmd = [
+                    "claude", "-p", prompt,
+                    "--output-format", "stream-json",
+                    "--verbose",
+                    "--permission-mode", "bypassPermissions",
+                ]
+            success, raw_output = self._run_agent_command(
+                agent,
+                cmd,
+                working_dir_expanded,
+                on_stdout_line=_append_tick_output,
+                on_stderr_line=_append_tick_output,
+            )
+            if not success:
+                raise RuntimeError(raw_output)
+            decision = self._parse_heartbeat_decision(raw_output)
+            decision_type = decision["decision"]
+            if decision_type == HeartbeatDecisionType.TRIGGER_TASK.value:
+                dedupe_key = decision.get("dedupe_key", "")
+                if self._heartbeat_trigger_suppressed(heartbeat, dedupe_key):
+                    decision_type = HeartbeatDecisionType.IDLE.value
+                    decision["decision"] = decision_type
+                    decision["reason"] = "Suppressed duplicate signal during cooldown or while prior task is still active"
+                else:
+                    task_prompt = decision.get("prompt") or heartbeat.get("action_prompt_template") or heartbeat["check_prompt"]
+                    task_title = decision.get("title") or f"Heartbeat: {heartbeat['name']}"
+                    task = Task(
+                        title=task_title,
+                        prompt=task_prompt,
+                        working_dir=heartbeat["working_dir"],
+                        schedule_type=ScheduleType.IMMEDIATE,
+                        agent=heartbeat.get("default_agent") or "claude",
+                        tags="heartbeat",
+                    )
+                    task_id = self.submit_task(task)
+                    if dedupe_key:
+                        self.db.upsert_heartbeat_dedup(hid, dedupe_key, task_id)
+                    self.db.update_heartbeat(
+                        hid,
+                        next_run_at=next_run_at,
+                        last_tick_at=now.isoformat(),
+                        last_decision=decision_type,
+                        last_error=None,
+                        last_triggered_at=now.isoformat(),
+                        last_dedupe_key=dedupe_key,
+                    )
+                    self.db.finish_heartbeat_tick(
+                        tick_id,
+                        status="triggered",
+                        decision_type=decision_type,
+                        decision_payload=decision,
+                        task_id=task_id,
+                        raw_output=("".join(output_chunks)[:500000] if output_chunks else None),
+                    )
+                    return
+            self.db.update_heartbeat(
+                hid,
+                next_run_at=next_run_at,
+                last_tick_at=now.isoformat(),
+                last_decision=decision_type,
+                last_error=None,
+                last_dedupe_key=decision.get("dedupe_key", "") or heartbeat.get("last_dedupe_key"),
+            )
+            self.db.finish_heartbeat_tick(
+                tick_id,
+                status="idle" if decision_type == HeartbeatDecisionType.IDLE.value else decision_type,
+                decision_type=decision_type,
+                decision_payload=decision,
+                raw_output=("".join(output_chunks)[:500000] if output_chunks else None),
+            )
+        except Exception as e:
+            logger.error(f"Heartbeat {hid} failed: {e}")
+            self.db.update_heartbeat(
+                hid,
+                next_run_at=next_run_at,
+                last_tick_at=now.isoformat(),
+                last_decision=HeartbeatDecisionType.ERROR.value,
+                last_error=str(e),
+            )
+            self.db.finish_heartbeat_tick(
+                tick_id,
+                status="error",
+                decision_type=HeartbeatDecisionType.ERROR.value,
+                raw_output=("".join(output_chunks)[:500000] if output_chunks else None),
+                error=str(e),
+            )
+        finally:
+            self._live_heartbeat_output.pop(tick_id, None)
+            self._active_heartbeats.pop(hid, None)
+
     def _parse_codex_event(self, event: dict) -> tuple:
         """Normalize a Codex JSONL event into (event_type, content) for storage.
 
@@ -1434,6 +2056,42 @@ def retry_task(self, task_id: int):
         self.db.update_task(task_id, status="pending", error=None)
         self._notify(task_id)
 
+    def trigger_heartbeat_now(self, heartbeat_id: int):
+        heartbeat = self.db.get_heartbeat(heartbeat_id)
+        if not heartbeat:
+            raise ValueError("heartbeat not found")
+        if heartbeat_id in self._active_heartbeats and self._active_heartbeats[heartbeat_id].is_alive():
+            raise ValueError("heartbeat already running")
+        self._spawn_heartbeat(heartbeat)
+
+    def pause_heartbeat(self, heartbeat_id: int):
+        heartbeat = self.db.get_heartbeat(heartbeat_id)
+        if not heartbeat:
+            raise ValueError("heartbeat not found")
+        self.db.update_heartbeat(heartbeat_id, enabled=0)
+
+    def resume_heartbeat(self, heartbeat_id: int):
+        heartbeat = self.db.get_heartbeat(heartbeat_id)
+        if not heartbeat:
+            raise ValueError("heartbeat not found")
+        next_run_at = self.db._compute_heartbeat_next_run_at(
+            Heartbeat(
+                id=heartbeat_id,
+                name=heartbeat["name"],
+                enabled=True,
+                working_dir=heartbeat["working_dir"],
+                schedule_type=HeartbeatScheduleType(heartbeat["schedule_type"]),
+                cron_expr=heartbeat.get("cron_expr"),
+                interval_seconds=heartbeat.get("interval_seconds"),
+                check_prompt=heartbeat["check_prompt"],
+                action_prompt_template=heartbeat.get("action_prompt_template") or "",
+                default_agent=heartbeat.get("default_agent") or "claude",
+                cooldown_seconds=int(heartbeat.get("cooldown_seconds") or 0),
+            ),
+            datetime.now(),
+        )
+        self.db.update_heartbeat(heartbeat_id, enabled=1, next_run_at=next_run_at)
+
 
 # ──────────────────────────── HTTP API Server ────────────────────────────
 
@@ -1471,11 +2129,111 @@ def do_OPTIONS(self):
         self._cors_headers()
         self.end_headers()
 
+    def _validate_heartbeat_payload(self, body: dict, existing: Optional[dict] = None) -> tuple[Optional[Heartbeat], Optional[tuple[dict, int]]]:
+        def _coerce_bool(value):
+            if isinstance(value, bool):
+                return value
+            if isinstance(value, str):
+                return value.lower() == "true"
+            return bool(value)
+
+        name = body.get("name", existing.get("name") if existing else "Untitled heartbeat")
+        check_prompt = body.get("check_prompt", existing.get("check_prompt") if existing else "")
+        if not check_prompt or not str(check_prompt).strip():
+            return None, ({"error": "check_prompt cannot be empty", "field": "check_prompt"}, 400)
+
+        working_dir = body.get("working_dir", existing.get("working_dir") if existing else ".")
+        if working_dir and working_dir != ".":
+            expanded = os.path.expanduser(working_dir)
+            if not os.path.isdir(expanded):
+                return None, ({"error": f"working_dir does not exist or is not a directory: {working_dir}", "field": "working_dir"}, 400)
+
+        schedule_value = body.get("schedule_type", existing.get("schedule_type") if existing else "interval")
+        try:
+            schedule_type = HeartbeatScheduleType(schedule_value)
+        except ValueError:
+            return None, ({"error": f"invalid heartbeat schedule_type: {schedule_value}", "field": "schedule_type"}, 400)
+
+        cron_expr = body.get("cron_expr", existing.get("cron_expr") if existing else None)
+        interval_seconds = body.get("interval_seconds", existing.get("interval_seconds") if existing else None)
+        if schedule_type == HeartbeatScheduleType.CRON:
+            if not cron_expr or not str(cron_expr).strip():
+                return None, ({"error": "cron_expr is required for cron heartbeat", "field": "cron_expr"}, 400)
+            if not croniter.is_valid(cron_expr):
+                return None, ({"error": f"invalid cron expression: {cron_expr}", "field": "cron_expr"}, 400)
+            interval_seconds = None
+        else:
+            try:
+                interval_seconds = int(interval_seconds)
+            except (TypeError, ValueError):
+                return None, ({"error": "interval_seconds must be a positive integer", "field": "interval_seconds"}, 400)
+            if interval_seconds <= 0:
+                return None, ({"error": "interval_seconds must be a positive integer", "field": "interval_seconds"}, 400)
+            cron_expr = None
+
+        cooldown_seconds = body.get("cooldown_seconds", existing.get("cooldown_seconds") if existing else 0)
+        try:
+            cooldown_seconds = int(cooldown_seconds or 0)
+        except (TypeError, ValueError):
+            return None, ({"error": "cooldown_seconds must be an integer", "field": "cooldown_seconds"}, 400)
+        if cooldown_seconds < 0:
+            return None, ({"error": "cooldown_seconds cannot be negative", "field": "cooldown_seconds"}, 400)
+
+        heartbeat = Heartbeat(
+            id=existing.get("id") if existing else None,
+            name=name,
+            enabled=_coerce_bool(body.get("enabled", existing.get("enabled") if existing else True)),
+            working_dir=working_dir,
+            schedule_type=schedule_type,
+            cron_expr=cron_expr,
+            interval_seconds=interval_seconds,
+            check_prompt=str(check_prompt),
+            action_prompt_template=str(body.get("action_prompt_template", existing.get("action_prompt_template") if existing else "")),
+            default_agent=str(body.get("default_agent", existing.get("default_agent") if existing else self.db.get_setting("default_agent", "claude"))),
+            cooldown_seconds=cooldown_seconds,
+            next_run_at=existing.get("next_run_at") if existing else None,
+            last_tick_at=existing.get("last_tick_at") if existing else None,
+            last_decision=existing.get("last_decision") if existing else None,
+            last_error=existing.get("last_error") if existing else None,
+            last_triggered_at=existing.get("last_triggered_at") if existing else None,
+            last_dedupe_key=existing.get("last_dedupe_key") if existing else None,
+        )
+        heartbeat.next_run_at = self.db._compute_heartbeat_next_run_at(heartbeat, datetime.now())
+        return heartbeat, None
+
     def do_GET(self):
         parsed = urlparse(self.path)
         path = parsed.path
 
-        if path == "/api/tasks":
+        if path == "/api/heartbeats":
+            self._json_response(self.db.get_all_heartbeats())
+
+        elif path.startswith("/api/heartbeats/") and "/ticks/" in path and path.endswith("/output"):
+            parts = path.split("/")
+            hid = int(parts[3])
+            tick_id = int(parts[5])
+            tick = self.db.get_heartbeat_tick(hid, tick_id)
+            if not tick:
+                self._json_response({"error": "not found"}, 404)
+                return
+            live = self.scheduler._live_heartbeat_output.get(tick_id, tick.get("raw_output") or "")
+            self._json_response({"output": live, "is_running": tick_id in self.scheduler._live_heartbeat_output})
+
+        elif path.startswith("/api/heartbeats/") and path.endswith("/ticks"):
+            hid = int(path.split("/")[3])
+            query = parse_qs(urlparse(self.path).query)
+            limit = int(query.get("limit", ["50"])[0])
+            self._json_response({"ticks": self.db.get_heartbeat_ticks(hid, limit=limit)})
+
+        elif path.startswith("/api/heartbeats/"):
+            hid = int(path.split("/")[3])
+            heartbeat = self.db.get_heartbeat(hid)
+            if heartbeat:
+                self._json_response(heartbeat)
+            else:
+                self._json_response({"error": "not found"}, 404)
+
+        elif path == "/api/tasks":
             tasks = self.db.get_all_tasks()
             # Attach dependency metadata to each task
             for t in tasks:
@@ -1628,7 +2386,44 @@ def do_POST(self):
         path = parsed.path
         body = self._read_body()
 
-        if path == "/api/tasks":
+        if path == "/api/heartbeats":
+            heartbeat, error = self._validate_heartbeat_payload(body)
+            if error:
+                payload, status = error
+                self._json_response(payload, status)
+                return
+            heartbeat_id = self.db.add_heartbeat(heartbeat)
+            self._json_response({"id": heartbeat_id, "status": "created"}, 201)
+
+        elif path.startswith("/api/heartbeats/") and path.endswith("/run-now"):
+            hid = int(path.split("/")[3])
+            try:
+                self.scheduler.trigger_heartbeat_now(hid)
+            except ValueError as e:
+                status = 404 if "not found" in str(e) else 409
+                self._json_response({"error": str(e)}, status)
+                return
+            self._json_response({"status": "scheduled"})
+
+        elif path.startswith("/api/heartbeats/") and path.endswith("/pause"):
+            hid = int(path.split("/")[3])
+            try:
+                self.scheduler.pause_heartbeat(hid)
+            except ValueError as e:
+                self._json_response({"error": str(e)}, 404)
+                return
+            self._json_response({"status": "paused"})
+
+        elif path.startswith("/api/heartbeats/") and path.endswith("/resume"):
+            hid = int(path.split("/")[3])
+            try:
+                self.scheduler.resume_heartbeat(hid)
+            except ValueError as e:
+                self._json_response({"error": str(e)}, 404)
+                return
+            self._json_response({"status": "resumed"})
+
+        elif path == "/api/tasks":
             # ── Input validation ──────────────────────────────────────
             prompt = body.get("prompt", "")
             if not prompt or not prompt.strip():
@@ -1951,6 +2746,37 @@ def do_PUT(self):
                 self.db.set_setting(key, str(value))
             self._json_response({"status": "updated"})
 
+        elif path.startswith("/api/heartbeats/") and path.count("/") == 3:
+            try:
+                hid = int(path.split("/")[3])
+            except (ValueError, IndexError):
+                self._json_response({"error": "invalid heartbeat id"}, 400)
+                return
+            heartbeat = self.db.get_heartbeat(hid)
+            if not heartbeat:
+                self._json_response({"error": "not found"}, 404)
+                return
+            validated, error = self._validate_heartbeat_payload(body, existing=heartbeat)
+            if error:
+                payload, status = error
+                self._json_response(payload, status)
+                return
+            updates = {
+                "name": validated.name,
+                "enabled": 1 if validated.enabled else 0,
+                "working_dir": validated.working_dir,
+                "schedule_type": validated.schedule_type.value,
+                "cron_expr": validated.cron_expr,
+                "interval_seconds": validated.interval_seconds,
+                "check_prompt": validated.check_prompt,
+                "action_prompt_template": validated.action_prompt_template,
+                "default_agent": validated.default_agent,
+                "cooldown_seconds": validated.cooldown_seconds,
+                "next_run_at": validated.next_run_at,
+            }
+            self.db.update_heartbeat(hid, **updates)
+            self._json_response(self.db.get_heartbeat(hid))
+
         elif path.startswith("/api/tasks/") and path.count("/") == 3:
             # PUT /api/tasks/{id} — edit a pending/scheduled/blocked task
             try:
@@ -2105,6 +2931,10 @@ def do_DELETE(self):
             dep_id = int(parts[5])
             self.db.remove_dependency(tid, dep_id)
             self._json_response({"status": "removed"})
+        elif parsed.path.startswith("/api/heartbeats/"):
+            hid = int(parsed.path.split("/")[3])
+            self.db.delete_heartbeat(hid)
+            self._json_response({"status": "deleted"})
         elif parsed.path.startswith("/api/tasks/"):
             tid = int(parsed.path.split("/")[3])
             self.db.delete_task(tid)
diff --git a/tests/test_heartbeat.py b/tests/test_heartbeat.py
new file mode 100644
index 0000000..77710d9
--- /dev/null
+++ b/tests/test_heartbeat.py
@@ -0,0 +1,144 @@
+import json
+
+from taskboard import (
+    Heartbeat,
+    HeartbeatScheduleType,
+    HeartbeatDecisionType,
+    ScheduleType,
+    TaskDB,
+    TaskScheduler,
+)
+
+
+def make_db(tmp_path):
+    return TaskDB(str(tmp_path / "agentforge-test.db"))
+
+
+def make_heartbeat(**overrides):
+    data = {
+        "name": "Repo watcher",
+        "working_dir": ".",
+        "schedule_type": HeartbeatScheduleType.INTERVAL,
+        "interval_seconds": 60,
+        "check_prompt": "Inspect repo and decide whether work is needed.",
+        "action_prompt_template": "Review the latest changes.",
+        "default_agent": "claude",
+        "cooldown_seconds": 300,
+    }
+    data.update(overrides)
+    return Heartbeat(**data)
+
+
+def test_add_and_get_heartbeat(tmp_path):
+    db = make_db(tmp_path)
+    heartbeat_id = db.add_heartbeat(make_heartbeat())
+
+    heartbeat = db.get_heartbeat(heartbeat_id)
+
+    assert heartbeat is not None
+    assert heartbeat["name"] == "Repo watcher"
+    assert heartbeat["enabled"] is True
+    assert heartbeat["schedule_type"] == HeartbeatScheduleType.INTERVAL.value
+    assert heartbeat["next_run_at"] is not None
+
+
+def test_heartbeat_trigger_creates_task_and_tick(tmp_path, monkeypatch):
+    db = make_db(tmp_path)
+    scheduler = TaskScheduler(db)
+    heartbeat_id = db.add_heartbeat(make_heartbeat())
+    heartbeat = db.get_heartbeat(heartbeat_id)
+
+    decision = {
+        "decision": HeartbeatDecisionType.TRIGGER_TASK.value,
+        "reason": "Found new changes",
+        "dedupe_key": "repo:abc123",
+        "title": "Review latest changes",
+        "prompt": "Review commit abc123.",
+        "metadata": {},
+    }
+    def fake_run(agent, cmd, cwd, on_stdout_line=None, on_stderr_line=None):
+        payload = json.dumps(decision)
+        if on_stdout_line:
+            on_stdout_line(payload)
+        return True, payload
+    monkeypatch.setattr(scheduler, "_run_agent_command", fake_run)
+
+    scheduler._execute_heartbeat(heartbeat)
+
+    tasks = db.get_all_tasks()
+    assert len(tasks) == 1
+    assert tasks[0]["title"] == "Review latest changes"
+    assert tasks[0]["prompt"] == "Review commit abc123."
+    assert tasks[0]["schedule_type"] == ScheduleType.IMMEDIATE.value
+
+    updated = db.get_heartbeat(heartbeat_id)
+    assert updated["last_decision"] == HeartbeatDecisionType.TRIGGER_TASK.value
+    assert updated["last_triggered_at"] is not None
+    assert updated["last_dedupe_key"] == "repo:abc123"
+
+    ticks = db.get_heartbeat_ticks(heartbeat_id)
+    assert len(ticks) == 1
+    assert ticks[0]["status"] == "triggered"
+    assert ticks[0]["task_id"] == tasks[0]["id"]
+    assert ticks[0]["raw_output"] == json.dumps(decision)
+
+
+def test_heartbeat_duplicate_signal_is_suppressed(tmp_path, monkeypatch):
+    db = make_db(tmp_path)
+    scheduler = TaskScheduler(db)
+    heartbeat_id = db.add_heartbeat(make_heartbeat())
+    heartbeat = db.get_heartbeat(heartbeat_id)
+
+    decision = {
+        "decision": HeartbeatDecisionType.TRIGGER_TASK.value,
+        "reason": "Found new changes",
+        "dedupe_key": "repo:abc123",
+        "title": "Review latest changes",
+        "prompt": "Review commit abc123.",
+        "metadata": {},
+    }
+    def fake_run(agent, cmd, cwd, on_stdout_line=None, on_stderr_line=None):
+        payload = json.dumps(decision)
+        if on_stdout_line:
+            on_stdout_line(payload)
+        return True, payload
+    monkeypatch.setattr(scheduler, "_run_agent_command", fake_run)
+
+    scheduler._execute_heartbeat(heartbeat)
+    scheduler._execute_heartbeat(db.get_heartbeat(heartbeat_id))
+
+    tasks = db.get_all_tasks()
+    assert len(tasks) == 1
+
+    heartbeat = db.get_heartbeat(heartbeat_id)
+    assert heartbeat["last_decision"] == HeartbeatDecisionType.IDLE.value
+
+    ticks = db.get_heartbeat_ticks(heartbeat_id)
+    assert len(ticks) == 2
+    assert ticks[0]["status"] == "idle"
+    assert "Suppressed duplicate signal" in json.loads(ticks[0]["decision_payload"])["reason"]
+
+
+def test_heartbeat_invalid_json_records_error(tmp_path, monkeypatch):
+    db = make_db(tmp_path)
+    scheduler = TaskScheduler(db)
+    heartbeat_id = db.add_heartbeat(make_heartbeat())
+    heartbeat = db.get_heartbeat(heartbeat_id)
+
+    def fake_run(agent, cmd, cwd, on_stdout_line=None, on_stderr_line=None):
+        if on_stdout_line:
+            on_stdout_line("not json")
+        return True, "not json"
+    monkeypatch.setattr(scheduler, "_run_agent_command", fake_run)
+
+    scheduler._execute_heartbeat(heartbeat)
+
+    updated = db.get_heartbeat(heartbeat_id)
+    assert updated["last_decision"] == HeartbeatDecisionType.ERROR.value
+    assert updated["last_error"]
+
+    ticks = db.get_heartbeat_ticks(heartbeat_id)
+    assert len(ticks) == 1
+    assert ticks[0]["status"] == "error"
+    assert ticks[0]["error"]
+    assert ticks[0]["raw_output"] == "not json"

From 9c13a49ab447dbd51926765abb44d41ed1bf3b66 Mon Sep 17 00:00:00 2001
From: hetaoBackend <hetao7@pku.edu.cn>
Date: Wed, 18 Mar 2026 15:37:50 +0800
Subject: [PATCH 2/4] chore: add backend quality baseline

---
 .github/workflows/ci.yml                      |   31 +
 .gitignore                                    |    4 +
 Makefile                                      |   26 +-
 channels/agent_utils.py                       |    2 +-
 channels/dir_utils.py                         |    5 +-
 channels/feishu_channel.py                    |  180 ++-
 channels/slack_channel.py                     |  142 +-
 channels/telegram_channel.py                  |   81 +-
 .../2026-03-18-backend-quality-baseline.md    |   72 +
 docs/todo.md                                  |    6 +
 pyproject.toml                                |   35 +
 skills/agentforge/scripts/agentforge_api.py   |    5 +-
 taskboard.py                                  | 1176 +++++++++++------
 taskboard_bus.py                              |   66 +-
 tests/conftest.py                             |    1 +
 tests/test_channel_utils.py                   |   92 ++
 tests/test_feishu_forwarded_messages.py       |  115 +-
 tests/test_heartbeat.py                       |    7 +-
 tests/test_taskboard_bus.py                   |  230 ++++
 tests/test_telegram_forwarded_messages.py     |  104 +-
 uv.lock                                       |  129 +-
 21 files changed, 1849 insertions(+), 660 deletions(-)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 docs/superpowers/plans/2026-03-18-backend-quality-baseline.md
 create mode 100644 tests/test_channel_utils.py
 create mode 100644 tests/test_taskboard_bus.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..740d7b3
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,31 @@
+name: Backend Quality
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  backend-quality:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run backend quality gate
+        run: make check
diff --git a/.gitignore b/.gitignore
index 505a3b1..5edfa31 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,7 @@ wheels/
 
 # Virtual environments
 .venv
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
diff --git a/Makefile b/Makefile
index a15b859..0985ae7 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: help build-backend build-electron package-dmg clean install-deps
+.PHONY: help build-backend build-electron package-dmg clean install-deps lint format format-check test test-cov check
 
 # 项目配置
 PROJECT_NAME = AgentForge
@@ -79,4 +79,26 @@ check-dmg:
 		ls -lh "$(DMG_OUTPUT)"; \
 	else \
 		echo "DMG文件不存在"; \
-	fi
\ No newline at end of file
+	fi
+
+lint:
+	@echo "运行 Ruff lint..."
+	uv run ruff check .
+
+format:
+	@echo "运行 Ruff format..."
+	uv run ruff format .
+
+format-check:
+	@echo "检查代码格式..."
+	uv run ruff format --check .
+
+test:
+	@echo "运行 Python 测试..."
+	uv run pytest
+
+test-cov:
+	@echo "运行 Python 测试并检查覆盖率..."
+	uv run pytest --cov --cov-report=term-missing
+
+check: lint format-check test-cov
diff --git a/channels/agent_utils.py b/channels/agent_utils.py
index ce1e52b..87ef3a3 100644
--- a/channels/agent_utils.py
+++ b/channels/agent_utils.py
@@ -9,7 +9,7 @@
 from __future__ import annotations
 
 import re
-from typing import Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
 
 if TYPE_CHECKING:
     from taskboard import TaskDB
diff --git a/channels/dir_utils.py b/channels/dir_utils.py
index 8b53576..7fea0cf 100644
--- a/channels/dir_utils.py
+++ b/channels/dir_utils.py
@@ -10,10 +10,10 @@
 
 from __future__ import annotations
 
+import json
 import os
 import re
-import json
-from typing import Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
 
 if TYPE_CHECKING:
     from taskboard import TaskDB
@@ -83,6 +83,7 @@ def extract_working_dir_with_claude(prompt: str) -> Optional[str]:
 
     try:
         import requests  # already in pyproject.toml
+
         resp = requests.post(
             "https://api.anthropic.com/v1/messages",
             headers={
diff --git a/channels/feishu_channel.py b/channels/feishu_channel.py
index 21bd3e0..2c26a2c 100644
--- a/channels/feishu_channel.py
+++ b/channels/feishu_channel.py
@@ -12,9 +12,9 @@
     feishu_default_working_dir  (working directory for tasks created from bot)
 """
 
+import base64
 import json
 import threading
-import base64
 from pathlib import Path
 from typing import TYPE_CHECKING, Optional
 
@@ -27,15 +27,16 @@
 try:
     import lark_oapi as lark
     from lark_oapi.api.im.v1 import (
-        CreateMessageRequest,
-        CreateMessageRequestBody,
         CreateMessageReactionRequest,
         CreateMessageReactionRequestBody,
+        CreateMessageRequest,
+        CreateMessageRequestBody,
+        Emoji,
         GetMessageResourceRequest,
         ReplyMessageRequest,
         ReplyMessageRequestBody,
-        Emoji,
     )
+
     FEISHU_AVAILABLE = True
 except ImportError:
     FEISHU_AVAILABLE = False
@@ -143,6 +144,7 @@ def start(self) -> None:
         except Exception as e:
             print(f"[Feishu] ERROR during initialization: {e}")
             import traceback
+
             traceback.print_exc()
 
     def stop(self) -> None:
@@ -169,6 +171,7 @@ def _run_ws(self):
         except Exception as e:
             print(f"[Feishu] WebSocket error: {e}")
             import traceback
+
             traceback.print_exc()
         finally:
             print("[Feishu] WebSocket thread exiting")
@@ -190,8 +193,10 @@ def send(self, msg: OutboundMessage) -> None:
             print(f"[Feishu] Task {task_id} not found in database")
             return
 
-        is_completed = (msg.type == OutboundMessageType.TASK_COMPLETED)
-        print(f"[Feishu] Sending notification for task {task_id} ({'completed' if is_completed else 'failed'})")
+        is_completed = msg.type == OutboundMessageType.TASK_COMPLETED
+        print(
+            f"[Feishu] Sending notification for task {task_id} ({'completed' if is_completed else 'failed'})"
+        )
 
         if is_completed:
             result_text = (msg.payload.get("result") or task.get("result") or "").strip()
@@ -199,7 +204,9 @@ def send(self, msg: OutboundMessage) -> None:
                 result_text = result_text[:10000] + "\n…(truncated)"
             content = result_text or "Done."
         else:
-            error_text = (msg.payload.get("error") or task.get("error") or "Unknown error").strip()[:800]
+            error_text = (msg.payload.get("error") or task.get("error") or "Unknown error").strip()[
+                :800
+            ]
             content = error_text
 
         # Try to reply in thread if we have an origin message
@@ -251,7 +258,7 @@ def _send_message(self, chat_id: str, content: str) -> Optional[str]:
                 "config": {"wide_screen_mode": True},
                 "elements": [{"tag": "markdown", "content": content}],
             }
-            print(f"[Feishu] Building CreateMessageRequest...")
+            print("[Feishu] Building CreateMessageRequest...")
             request = (
                 CreateMessageRequest.builder()
                 .receive_id_type(receive_id_type)
@@ -264,9 +271,11 @@ def _send_message(self, chat_id: str, content: str) -> Optional[str]:
                 )
                 .build()
             )
-            print(f"[Feishu] Calling im.v1.message.create()...")
+            print("[Feishu] Calling im.v1.message.create()...")
             response = self._client.im.v1.message.create(request)
-            print(f"[Feishu] Response received: success={response.success()}, code={response.code}, msg={response.msg}")
+            print(
+                f"[Feishu] Response received: success={response.success()}, code={response.code}, msg={response.msg}"
+            )
             if response.success():
                 message_id = response.data.message_id
                 print(f"[Feishu] Message sent successfully, message_id: {message_id}")
@@ -277,12 +286,15 @@ def _send_message(self, chat_id: str, content: str) -> Optional[str]:
         except Exception as e:
             print(f"[Feishu] Error sending message: {e}")
             import traceback
+
             traceback.print_exc()
             return None
 
     def _reply_message(self, parent_message_id: str, content: str) -> Optional[str]:
         """Reply to a specific message (thread-style). Returns the sent message_id or None."""
-        print(f"[Feishu] _reply_message called, parent_message_id: {parent_message_id}, content length: {len(content)}")
+        print(
+            f"[Feishu] _reply_message called, parent_message_id: {parent_message_id}, content length: {len(content)}"
+        )
         if not self._client:
             print("[Feishu] Client not initialized in _reply_message")
             return None
@@ -303,9 +315,11 @@ def _reply_message(self, parent_message_id: str, content: str) -> Optional[str]:
                 )
                 .build()
             )
-            print(f"[Feishu] Calling im.v1.message.reply()...")
+            print("[Feishu] Calling im.v1.message.reply()...")
             response = self._client.im.v1.message.reply(request)
-            print(f"[Feishu] Reply response: success={response.success()}, code={response.code}, msg={response.msg}")
+            print(
+                f"[Feishu] Reply response: success={response.success()}, code={response.code}, msg={response.msg}"
+            )
             if response.success():
                 message_id = response.data.message_id
                 print(f"[Feishu] Reply sent successfully, message_id: {message_id}")
@@ -316,6 +330,7 @@ def _reply_message(self, parent_message_id: str, content: str) -> Optional[str]:
         except Exception as e:
             print(f"[Feishu] Error replying to message: {e}")
             import traceback
+
             traceback.print_exc()
             return None
 
@@ -348,8 +363,9 @@ def _get_usage_stats(self) -> str:
         """Compute current 5-hour block usage via claude-monitor library."""
         try:
             from datetime import datetime, timezone
-            from claude_monitor.data.analysis import analyze_usage
+
             from claude_monitor.core.plans import Plans
+            from claude_monitor.data.analysis import analyze_usage
             from claude_monitor.utils.time_utils import TimezoneHandler
 
             data = analyze_usage(hours_back=192, quick_start=False, use_cache=False)
@@ -449,7 +465,7 @@ def _extract_forwarded_content(self, message) -> Optional[dict]:
                     "sender_id": content.get("sender_id"),
                     "timestamp": content.get("create_time"),
                     "text": content.get("text", ""),
-                    "images": content.get("images", [])
+                    "images": content.get("images", []),
                 }
             except json.JSONDecodeError:
                 pass
@@ -469,7 +485,9 @@ def _extract_forwarded_content(self, message) -> Optional[dict]:
 
                 # 如果 lang_body 是列表（简化的 content 格式），直接遍历
                 # 否则从 lang_body 中获取 content
-                paragraphs = lang_body if isinstance(lang_body, list) else lang_body.get("content", [])
+                paragraphs = (
+                    lang_body if isinstance(lang_body, list) else lang_body.get("content", [])
+                )
 
                 # 遍历内容查找引用 block
                 for para in paragraphs:
@@ -485,7 +503,7 @@ def _extract_forwarded_content(self, message) -> Optional[dict]:
                                 "sender_name": sender_name,
                                 "sender_id": quote_user.get("open_id"),
                                 "text": quote_text,
-                                "timestamp": elem.get("create_time")
+                                "timestamp": elem.get("create_time"),
                             }
 
                         # 嵌套消息（可能是转发）
@@ -497,7 +515,7 @@ def _extract_forwarded_content(self, message) -> Optional[dict]:
                                 "sender_id": nested.get("sender_id"),
                                 "timestamp": nested.get("create_time"),
                                 "text": nested.get("text", ""),
-                                "images": nested.get("images", [])
+                                "images": nested.get("images", []),
                             }
 
             except (json.JSONDecodeError, AttributeError):
@@ -528,6 +546,7 @@ def _format_forwarded_prompt(self, original_content: str, forwarded: dict) -> st
 
         if forwarded.get("timestamp"):
             from datetime import datetime
+
             ts = datetime.fromtimestamp(forwarded["timestamp"])
             parts.append(f"时间: {ts.strftime('%Y-%m-%d %H:%M')}")
 
@@ -578,13 +597,13 @@ def _download_image(self, message_id: str, image_key: str) -> Optional[str]:
             image_data = response.raw.content
 
             # Detect actual image format from magic bytes
-            if image_data.startswith(b'\xff\xd8\xff'):
+            if image_data.startswith(b"\xff\xd8\xff"):
                 extension = "jpg"
-            elif image_data.startswith(b'\x89PNG\r\n\x1a\n'):
+            elif image_data.startswith(b"\x89PNG\r\n\x1a\n"):
                 extension = "png"
-            elif image_data.startswith(b'GIF87a') or image_data.startswith(b'GIF89a'):
+            elif image_data.startswith(b"GIF87a") or image_data.startswith(b"GIF89a"):
                 extension = "gif"
-            elif image_data.startswith(b'RIFF') and b'WEBP' in image_data[:12]:
+            elif image_data.startswith(b"RIFF") and b"WEBP" in image_data[:12]:
                 extension = "webp"
             else:
                 # Default to jpg if unknown
@@ -602,6 +621,7 @@ def _download_image(self, message_id: str, image_key: str) -> Optional[str]:
         except Exception as e:
             print(f"[Feishu] Error downloading image {image_key}: {e}")
             import traceback
+
             traceback.print_exc()
             return None
 
@@ -609,7 +629,7 @@ def _download_image(self, message_id: str, image_key: str) -> Optional[str]:
 
     def _on_bot_added(self, data) -> None:
         """Called when the bot is added to a chat (including P2P when a user follows the bot)."""
-        print(f"[Feishu] _on_bot_added called")
+        print("[Feishu] _on_bot_added called")
         try:
             event = data.event
             chat_id = getattr(event, "chat_id", None)
@@ -621,6 +641,7 @@ def _on_bot_added(self, data) -> None:
         except Exception as e:
             print(f"[Feishu] _on_bot_added error: {e}")
             import traceback
+
             traceback.print_exc()
 
     def _on_message_sync(self, data) -> None:
@@ -628,21 +649,22 @@ def _on_message_sync(self, data) -> None:
         print(f"[Feishu] _on_message_sync called, data type: {type(data)}")
         try:
             self._handle_inbound(data)
-            print(f"[Feishu] Message handled successfully")
+            print("[Feishu] Message handled successfully")
         except Exception as e:
             print(f"[Feishu] Inbound handler error: {e}")
             import traceback
+
             traceback.print_exc()
 
     def _handle_inbound(self, data) -> None:
         """Parse incoming Feishu message and act on it."""
-        print(f"[Feishu] _handle_inbound processing message...")
+        print("[Feishu] _handle_inbound processing message...")
         event = data.event
         message = event.message
         sender = event.sender
 
         if sender.sender_type == "bot":
-            print(f"[Feishu] Ignoring message from bot (self)")
+            print("[Feishu] Ignoring message from bot (self)")
             return  # ignore self-messages
 
         msg_type = message.message_type
@@ -665,9 +687,9 @@ def _handle_inbound(self, data) -> None:
                 else:
                     # Try language-specific keys
                     lang_body = (
-                        post_body.get("zh_cn") or
-                        post_body.get("en_us") or
-                        next(iter(post_body.values()), {})
+                        post_body.get("zh_cn")
+                        or post_body.get("en_us")
+                        or next(iter(post_body.values()), {})
                     )
 
                 title_part = lang_body.get("title", "").strip()
@@ -703,6 +725,7 @@ def _handle_inbound(self, data) -> None:
             except (json.JSONDecodeError, AttributeError, StopIteration) as e:
                 print(f"[Feishu] Failed to parse post message: {e}")
                 import traceback
+
                 traceback.print_exc()
                 # Don't use raw content as fallback - it's the JSON structure
                 content = ""
@@ -733,7 +756,9 @@ def _handle_inbound(self, data) -> None:
         # ── 检测转发/引用消息 ───────────────────────────────────
         forwarded = self._extract_forwarded_content(message)
         if forwarded:
-            print(f"[Feishu] Detected forwarded/quoted message from {forwarded.get('sender_name', 'unknown')}")
+            print(
+                f"[Feishu] Detected forwarded/quoted message from {forwarded.get('sender_name', 'unknown')}"
+            )
             content = self._format_forwarded_prompt(content, forwarded)
             # 处理转发中包含的图片（如果有）
             for img_info in forwarded.get("images", []):
@@ -744,11 +769,11 @@ def _handle_inbound(self, data) -> None:
                         image_paths.append(img_path)
 
         if not content:
-            print(f"[Feishu] Empty content after processing, ignoring")
+            print("[Feishu] Empty content after processing, ignoring")
             return
 
         # Acknowledge with a "get" reaction
-        print(f"[Feishu] Adding reaction to message...")
+        print("[Feishu] Adding reaction to message...")
         self._add_reaction(message.message_id, "OK")
 
         sender_id = sender.sender_id.open_id if sender.sender_id else "unknown"
@@ -765,6 +790,7 @@ def _handle_inbound(self, data) -> None:
         # ── command: /dir <path> — switch working directory ──────
         if content.startswith("/dir ") or content.startswith("/cd "):
             from channels.dir_utils import handle_dir_command
+
             reply = handle_dir_command(content, "feishu", self.db)
             if reply:
                 self._send_message(reply_to, reply)
@@ -773,6 +799,7 @@ def _handle_inbound(self, data) -> None:
         # ── command: /agent <name> — switch coding agent ─────────
         if content.startswith("/agent "):
             from channels.agent_utils import handle_agent_command
+
             reply = handle_agent_command(content, "feishu", self.db)
             if reply:
                 self._send_message(reply_to, reply)
@@ -786,7 +813,7 @@ def _handle_inbound(self, data) -> None:
 
         # ── command: /resume <task_id> <message> ────────────────
         if content.startswith("/resume "):
-            print(f"[Feishu] Processing /resume command")
+            print("[Feishu] Processing /resume command")
             parts = content[8:].strip().split(" ", 1)
             if len(parts) >= 2 and parts[0].isdigit():
                 tid = int(parts[0])
@@ -816,20 +843,25 @@ def _handle_inbound(self, data) -> None:
                     print(f"[Feishu] Task {tid} not found or no session_id")
             else:
                 self._send_message(reply_to, "Usage: `/resume <task_id> <message>`")
-                print(f"[Feishu] Invalid /resume syntax")
+                print("[Feishu] Invalid /resume syntax")
             return
 
         # ── command: /status <task_id> ───────────────────────────
         if content.startswith("/status "):
-            print(f"[Feishu] Processing /status command")
+            print("[Feishu] Processing /status command")
             parts = content[8:].strip().split()
             if parts and parts[0].isdigit():
                 tid = int(parts[0])
                 task = self.db.get_task(tid)
                 if task:
                     s = task["status"]
-                    icon = {"completed": "✅", "failed": "❌", "running": "⏳",
-                            "pending": "🕐", "cancelled": "🚫"}.get(s, "❓")
+                    icon = {
+                        "completed": "✅",
+                        "failed": "❌",
+                        "running": "⏳",
+                        "pending": "🕐",
+                        "cancelled": "🚫",
+                    }.get(s, "❓")
                     self._send_message(
                         reply_to,
                         f"{icon} **Task #{tid}** — {s}\n\n**{task['title']}**",
@@ -841,17 +873,26 @@ def _handle_inbound(self, data) -> None:
             return
 
         # ── filter system notifications ───────────────────────────
-        if any(keyword in content.lower() for keyword in [
-            "notification", "任务完成", "任务失败", "任务状态",
-            "任务已", "task completed", "task failed", "task status"
-        ]):
-            print(f"[Feishu] Ignoring system notification")
+        if any(
+            keyword in content.lower()
+            for keyword in [
+                "notification",
+                "任务完成",
+                "任务失败",
+                "任务状态",
+                "任务已",
+                "task completed",
+                "task failed",
+                "task status",
+            ]
+        ):
+            print("[Feishu] Ignoring system notification")
             return
 
         # ── detect reply in thread → resume task session ─────────
         # Check parent_id (direct reply) and root_id (any message in thread)
-        parent_id = getattr(message, 'parent_id', None) or None
-        root_id = getattr(message, 'root_id', None) or None
+        parent_id = getattr(message, "parent_id", None) or None
+        root_id = getattr(message, "root_id", None) or None
         is_thread_msg = bool(parent_id or root_id)
 
         if is_thread_msg:
@@ -876,7 +917,9 @@ def _handle_inbound(self, data) -> None:
                     db_task = self.db.get_task_by_feishu_root_msg(msg_id)
                     if db_task:
                         task_id = db_task["id"]
-                        print(f"[Feishu] Recovered task {task_id} from DB via feishu_root_msg_id={msg_id}")
+                        print(
+                            f"[Feishu] Recovered task {task_id} from DB via feishu_root_msg_id={msg_id}"
+                        )
                         break
 
             # Determine which message to reply to in the thread
@@ -910,14 +953,15 @@ def _handle_inbound(self, data) -> None:
                     print(f"[Feishu] Task {task_id} cannot be resumed")
                     return
             else:
-                print(f"[Feishu] Thread message but no matching task found, creating new task")
+                print("[Feishu] Thread message but no matching task found, creating new task")
         else:
-            print(f"[Feishu] Message is not a reply (no parent_id or root_id)")
+            print("[Feishu] Message is not a reply (no parent_id or root_id)")
 
         # ── default: create a new task from message text ─────────
-        print(f"[Feishu] Creating new task from message")
+        print("[Feishu] Creating new task from message")
         print(f"[Feishu] image_paths to attach: {image_paths}")
         from channels.dir_utils import resolve_working_dir
+
         working_dir = resolve_working_dir(content, "feishu", self.db)
         title = content[:60] + ("…" if len(content) > 60 else "")
 
@@ -932,22 +976,26 @@ def _handle_inbound(self, data) -> None:
                     # Detect media type from file extension
                     ext = Path(img_path).suffix.lower()
                     media_type_map = {
-                        ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
-                        ".png": "image/png", ".gif": "image/gif", ".webp": "image/webp"
+                        ".jpg": "image/jpeg",
+                        ".jpeg": "image/jpeg",
+                        ".png": "image/png",
+                        ".gif": "image/gif",
+                        ".webp": "image/webp",
                     }
                     media_type = media_type_map.get(ext, "image/jpeg")
 
-                    prompt_images.append({
-                        "name": Path(img_path).name,
-                        "media_type": media_type,
-                        "data": img_data
-                    })
-                    print(f"[Feishu] Converted {img_path} to prompt_images ({media_type}, {len(img_data)} bytes)")
+                    prompt_images.append(
+                        {"name": Path(img_path).name, "media_type": media_type, "data": img_data}
+                    )
+                    print(
+                        f"[Feishu] Converted {img_path} to prompt_images ({media_type}, {len(img_data)} bytes)"
+                    )
                 except Exception as e:
                     print(f"[Feishu] Failed to convert image {img_path} to base64: {e}")
 
-        from taskboard import Task, ScheduleType
         from channels.agent_utils import resolve_agent
+        from taskboard import ScheduleType, Task
+
         new_task = Task(
             title=f"[Feishu] {title}",
             prompt=content,
@@ -959,12 +1007,20 @@ def _handle_inbound(self, data) -> None:
             feishu_root_msg_id=message.message_id,
             agent=resolve_agent("feishu", self.db),
         )
-        print(f"[Feishu] Task object created with {len(image_paths)} image_paths and {len(prompt_images)} prompt_images")
+        print(
+            f"[Feishu] Task object created with {len(image_paths)} image_paths and {len(prompt_images)} prompt_images"
+        )
         task_id = self.scheduler.submit_task(new_task)
         print(f"[Feishu] Task {task_id} submitted, verifying in DB...")
         created_task = self.db.get_task(task_id)
-        print(f"[Feishu] Task {task_id} in DB has image_paths: {created_task.get('image_paths')}, prompt_images: {len(created_task.get('prompt_images', []))} items")
-        img_info = f" (with {len(image_paths)} image{'s' if len(image_paths) != 1 else ''})" if image_paths else ""
+        print(
+            f"[Feishu] Task {task_id} in DB has image_paths: {created_task.get('image_paths')}, prompt_images: {len(created_task.get('prompt_images', []))} items"
+        )
+        img_info = (
+            f" (with {len(image_paths)} image{'s' if len(image_paths) != 1 else ''})"
+            if image_paths
+            else ""
+        )
 
         # Reply with a brief running hint and track origin for completion notification
         self._reply_message(message.message_id, f"Task #{task_id} is running…")
@@ -972,5 +1028,7 @@ def _handle_inbound(self, data) -> None:
             self._task_origin[task_id] = (reply_to, message.message_id, message.message_id)
         with self._root_msg_lock:
             self._root_msg_map[message.message_id] = task_id
-        print(f"[Feishu] Task {task_id} origin tracked: reply_to={reply_to}, root_msg={message.message_id}")
+        print(
+            f"[Feishu] Task {task_id} origin tracked: reply_to={reply_to}, root_msg={message.message_id}"
+        )
         print(f"[Feishu] New task {task_id} created and queued with {len(image_paths)} images")
diff --git a/channels/slack_channel.py b/channels/slack_channel.py
index e1f3ae6..21d3d41 100644
--- a/channels/slack_channel.py
+++ b/channels/slack_channel.py
@@ -11,7 +11,6 @@
 """
 
 import os
-import json
 import threading
 import traceback
 from typing import TYPE_CHECKING, Optional
@@ -26,13 +25,13 @@ def _require_slack():
     try:
         from slack_sdk import WebClient
         from slack_sdk.socket_mode import SocketModeClient
-        from slack_sdk.socket_mode.response import SocketModeResponse
         from slack_sdk.socket_mode.request import SocketModeRequest
+        from slack_sdk.socket_mode.response import SocketModeResponse
+
         return WebClient, SocketModeClient, SocketModeResponse, SocketModeRequest
     except ImportError as e:
         raise ImportError(
-            "slack-sdk is required for SlackChannel. "
-            "Install it with: uv add slack-sdk"
+            "slack-sdk is required for SlackChannel. Install it with: uv add slack-sdk"
         ) from e
 
 
@@ -60,8 +59,14 @@ def _require_slack():
 class SlackChannel(Channel):
     """Slack channel integration using Socket Mode."""
 
-    def __init__(self, bus: MessageBus, db: "TaskDB", scheduler: "TaskScheduler",
-                 bot_token: str = "", app_token: str = ""):
+    def __init__(
+        self,
+        bus: MessageBus,
+        db: "TaskDB",
+        scheduler: "TaskScheduler",
+        bot_token: str = "",
+        app_token: str = "",
+    ):
         super().__init__("slack", bus, db)
         self.scheduler = scheduler
 
@@ -92,8 +97,10 @@ def __init__(self, bus: MessageBus, db: "TaskDB", scheduler: "TaskScheduler",
         # Subscribe to outbound bus messages for task notifications
         bus.subscribe_outbound(self._on_outbound)
 
-        print(f"[Slack] Initialized. bot_token={'set' if self.bot_token else 'MISSING'}, "
-              f"app_token={'set' if self.app_token else 'MISSING'}")
+        print(
+            f"[Slack] Initialized. bot_token={'set' if self.bot_token else 'MISSING'}, "
+            f"app_token={'set' if self.app_token else 'MISSING'}"
+        )
 
     # ── lifecycle ────────────────────────────────────────────────
 
@@ -113,7 +120,9 @@ def start(self) -> None:
         try:
             resp = self._web_client.auth_test()
             self._bot_user_id = resp["user_id"]
-            print(f"[Slack] auth_test OK — bot_user_id={self._bot_user_id}, team={resp.get('team', '?')}, user={resp.get('user', '?')}")
+            print(
+                f"[Slack] auth_test OK — bot_user_id={self._bot_user_id}, team={resp.get('team', '?')}, user={resp.get('user', '?')}"
+            )
         except Exception as e:
             print(f"[Slack] auth_test FAILED: {e}")
             traceback.print_exc()
@@ -150,7 +159,9 @@ def stop(self) -> None:
     def _handle_socket_request(self, client, req) -> None:
         from slack_sdk.socket_mode.response import SocketModeResponse
 
-        print(f"[Slack] <<< Socket request received: type={req.type}, envelope_id={req.envelope_id[:12]}...")
+        print(
+            f"[Slack] <<< Socket request received: type={req.type}, envelope_id={req.envelope_id[:12]}..."
+        )
 
         # Acknowledge immediately (Slack requires < 3s ack)
         client.send_socket_mode_response(SocketModeResponse(envelope_id=req.envelope_id))
@@ -164,13 +175,15 @@ def _handle_socket_request(self, client, req) -> None:
         event = payload.get("event", {})
         event_type = event.get("type", "")
 
-        print(f"[Slack]     Event type={event_type}, "
-              f"user={event.get('user', '?')}, "
-              f"channel={event.get('channel', '?')}, "
-              f"channel_type={event.get('channel_type', '?')}, "
-              f"bot_id={event.get('bot_id', 'none')}, "
-              f"subtype={event.get('subtype', 'none')}, "
-              f"text={repr((event.get('text', '') or '')[:80])}")
+        print(
+            f"[Slack]     Event type={event_type}, "
+            f"user={event.get('user', '?')}, "
+            f"channel={event.get('channel', '?')}, "
+            f"channel_type={event.get('channel_type', '?')}, "
+            f"bot_id={event.get('bot_id', 'none')}, "
+            f"subtype={event.get('subtype', 'none')}, "
+            f"text={repr((event.get('text', '') or '')[:80])}"
+        )
 
         # Handle message events
         try:
@@ -190,16 +203,20 @@ def _handle_message_event(self, event: dict) -> None:
         """Handle DM messages (channel_type == 'im')."""
         # Only process DMs, not channel messages (those come via app_mention)
         if event.get("channel_type") != "im":
-            print(f"[Slack]     message event skipped: channel_type={event.get('channel_type')!r} (not 'im')")
+            print(
+                f"[Slack]     message event skipped: channel_type={event.get('channel_type')!r} (not 'im')"
+            )
             return
         # Ignore bot messages and message edits
         if event.get("bot_id") or event.get("subtype"):
-            print(f"[Slack]     message event skipped: bot_id={event.get('bot_id')}, subtype={event.get('subtype')}")
+            print(
+                f"[Slack]     message event skipped: bot_id={event.get('bot_id')}, subtype={event.get('subtype')}"
+            )
             return
 
         user_id = event.get("user", "")
         if user_id == self._bot_user_id:
-            print(f"[Slack]     message event skipped: message from self (bot)")
+            print("[Slack]     message event skipped: message from self (bot)")
             return
 
         text = event.get("text", "").strip()
@@ -213,12 +230,14 @@ def _handle_message_event(self, event: dict) -> None:
     def _handle_mention_event(self, event: dict) -> None:
         """Handle @bot mentions in channels."""
         if event.get("bot_id") or event.get("subtype"):
-            print(f"[Slack]     mention event skipped: bot_id={event.get('bot_id')}, subtype={event.get('subtype')}")
+            print(
+                f"[Slack]     mention event skipped: bot_id={event.get('bot_id')}, subtype={event.get('subtype')}"
+            )
             return
 
         user_id = event.get("user", "")
         if user_id == self._bot_user_id:
-            print(f"[Slack]     mention event skipped: mention from self (bot)")
+            print("[Slack]     mention event skipped: mention from self (bot)")
             return
 
         # Strip the mention prefix (<@BOTID> ...) from the text
@@ -226,13 +245,15 @@ def _handle_mention_event(self, event: dict) -> None:
         if self._bot_user_id:
             mention_prefix = f"<@{self._bot_user_id}>"
             if text.startswith(mention_prefix):
-                text = text[len(mention_prefix):].strip()
+                text = text[len(mention_prefix) :].strip()
 
         channel_id = event.get("channel", "")
         thread_ts = event.get("thread_ts")
         msg_ts = event.get("ts")
 
-        print(f"[Slack]     Mention from user={user_id}, channel={channel_id}, text={repr(text[:80])}")
+        print(
+            f"[Slack]     Mention from user={user_id}, channel={channel_id}, text={repr(text[:80])}"
+        )
         self._handle_user_message(text, channel_id, thread_ts, msg_ts)
 
     def _handle_app_home_opened(self, event: dict) -> None:
@@ -253,8 +274,9 @@ def _handle_app_home_opened(self, event: dict) -> None:
 
     # ── unified message handler ───────────────────────────────────
 
-    def _handle_user_message(self, text: str, channel_id: str,
-                             thread_ts: Optional[str], msg_ts: str) -> None:
+    def _handle_user_message(
+        self, text: str, channel_id: str, thread_ts: Optional[str], msg_ts: str
+    ) -> None:
         """Handle any user message: commands, resume-by-reply, or create task."""
         if not text:
             self._reply(channel_id, msg_ts, HELP_TEXT)
@@ -274,10 +296,12 @@ def _handle_user_message(self, text: str, channel_id: str,
                 self._cmd_resume(args, channel_id, msg_ts)
             elif cmd in ("/dir", "/cd"):
                 from channels.dir_utils import handle_dir_command
+
                 reply = handle_dir_command(text, "slack", self.db)
                 self._reply(channel_id, msg_ts, reply or HELP_TEXT)
             elif cmd == "/agent":
                 from channels.agent_utils import handle_agent_command
+
                 reply = handle_agent_command(text, "slack", self.db)
                 self._reply(channel_id, msg_ts, reply or HELP_TEXT)
             elif cmd == "/help":
@@ -312,16 +336,14 @@ def _handle_user_message(self, text: str, channel_id: str,
                     with self._origin_lock:
                         self._task_origin[task_id] = (channel_id, thread_ts, msg_ts)
                     self._add_reaction(channel_id, msg_ts, "eyes")
-                    self._reply(
-                        channel_id, thread_ts,
-                        ":arrow_forward:"
-                    )
+                    self._reply(channel_id, thread_ts, ":arrow_forward:")
                     print(f"[Slack] Auto-resuming task {task_id} from thread reply")
                     return
                 else:
                     self._reply(
-                        channel_id, thread_ts,
-                        f":x: Task *#{task_id}* has no saved session to resume."
+                        channel_id,
+                        thread_ts,
+                        f":x: Task *#{task_id}* has no saved session to resume.",
                     )
                     return
 
@@ -332,11 +354,12 @@ def _handle_user_message(self, text: str, channel_id: str,
 
     def _create_task(self, text: str, channel_id: str, thread_ts: str) -> None:
         """Create a new task from any message."""
-        from taskboard import Task, ScheduleType
+        from taskboard import ScheduleType, Task
 
         title = text[:60] + ("…" if len(text) > 60 else "")
-        from channels.dir_utils import resolve_working_dir
         from channels.agent_utils import resolve_agent
+        from channels.dir_utils import resolve_working_dir
+
         task = Task(
             title=f"[Slack] {title}",
             prompt=text,
@@ -350,8 +373,10 @@ def _create_task(self, text: str, channel_id: str, thread_ts: str) -> None:
 
         with self._origin_lock:
             self._task_origin[task_id] = (channel_id, thread_ts, thread_ts)
-            print(f"[Slack] Origin set for task #{task_id}: channel={channel_id}, thread_ts={thread_ts}, "
-                  f"self_id={id(self)}, origin_dict_id={id(self._task_origin)}")
+            print(
+                f"[Slack] Origin set for task #{task_id}: channel={channel_id}, thread_ts={thread_ts}, "
+                f"self_id={id(self)}, origin_dict_id={id(self._task_origin)}"
+            )
 
         # Track thread root ts → task_id so replies in the thread can resume
         with self._thread_ts_lock:
@@ -409,8 +434,9 @@ def _cmd_cancel(self, args: str, channel_id: str, thread_ts: str) -> None:
 
         if task["status"] in ("completed", "failed", "cancelled"):
             self._reply(
-                channel_id, thread_ts,
-                f":information_source: Task #{task_id} is already `{task['status']}`."
+                channel_id,
+                thread_ts,
+                f":information_source: Task #{task_id} is already `{task['status']}`.",
             )
             return
 
@@ -431,7 +457,9 @@ def _cmd_resume(self, args: str, channel_id: str, thread_ts: str) -> None:
 
         task = self.db.get_task(tid)
         if not task or not task.get("session_id"):
-            self._reply(channel_id, thread_ts, f":x: Task #{tid} not found or has no saved session.")
+            self._reply(
+                channel_id, thread_ts, f":x: Task #{tid} not found or has no saved session."
+            )
             return
 
         self.db.update_task(
@@ -457,9 +485,11 @@ def send(self, msg: OutboundMessage) -> None:
         task_id = msg.task_id
         with self._origin_lock:
             origin = self._task_origin.get(task_id)
-            print(f"[Slack] send() task_id={task_id} (type={type(task_id).__name__}), "
-                  f"origin={origin}, keys={list(self._task_origin.keys())}, "
-                  f"self_id={id(self)}, origin_dict_id={id(self._task_origin)}")
+            print(
+                f"[Slack] send() task_id={task_id} (type={type(task_id).__name__}), "
+                f"origin={origin}, keys={list(self._task_origin.keys())}, "
+                f"self_id={id(self)}, origin_dict_id={id(self._task_origin)}"
+            )
 
         # Build notification text
         if msg.type == OutboundMessageType.TASK_COMPLETED:
@@ -488,7 +518,11 @@ def send(self, msg: OutboundMessage) -> None:
                 if dm_ch:
                     channel_id = dm_ch
                     thread_ts = None
-                    status_emoji = ":white_check_mark:" if msg.type == OutboundMessageType.TASK_COMPLETED else ":x:"
+                    status_emoji = (
+                        ":white_check_mark:"
+                        if msg.type == OutboundMessageType.TASK_COMPLETED
+                        else ":x:"
+                    )
                     text = f"{status_emoji} *{title}*\n{text}"
                     print(f"[Slack] Falling back to P2P DM with user {dm_user}")
                 else:
@@ -497,10 +531,16 @@ def send(self, msg: OutboundMessage) -> None:
             elif default_channel:
                 channel_id = default_channel
                 thread_ts = None
-                status_emoji = ":white_check_mark:" if msg.type == OutboundMessageType.TASK_COMPLETED else ":x:"
+                status_emoji = (
+                    ":white_check_mark:"
+                    if msg.type == OutboundMessageType.TASK_COMPLETED
+                    else ":x:"
+                )
                 text = f"{status_emoji} *{title}*\n{text}"
             else:
-                print(f"[Slack] No origin, no known user, no slack_default_channel for task #{task_id}, skipping")
+                print(
+                    f"[Slack] No origin, no known user, no slack_default_channel for task #{task_id}, skipping"
+                )
                 return
 
         print(f"[Slack] Sending outbound notification for task #{task_id}: {msg.type.name}")
@@ -562,22 +602,26 @@ def _do():
 
     def _reply(self, channel_id: str, thread_ts: Optional[str], text: str) -> None:
         if not self._web_client:
-            print(f"[Slack] _reply skipped: no web_client")
+            print("[Slack] _reply skipped: no web_client")
             return
         try:
-            print(f"[Slack] >>> Sending message to channel={channel_id}, thread={thread_ts}, len={len(text)}")
+            print(
+                f"[Slack] >>> Sending message to channel={channel_id}, thread={thread_ts}, len={len(text)}"
+            )
             self._web_client.chat_postMessage(
                 channel=channel_id,
                 thread_ts=thread_ts,
                 text=text,
                 mrkdwn=True,
             )
-            print(f"[Slack] >>> Message sent OK")
+            print("[Slack] >>> Message sent OK")
         except Exception as e:
             print(f"[Slack] >>> chat_postMessage FAILED: {e}")
             traceback.print_exc()
 
-    def _reply_return_ts(self, channel_id: str, thread_ts: Optional[str], text: str) -> Optional[str]:
+    def _reply_return_ts(
+        self, channel_id: str, thread_ts: Optional[str], text: str
+    ) -> Optional[str]:
         """Send a message and return its ts (for tracking notification threads)."""
         if not self._web_client:
             return None
diff --git a/channels/telegram_channel.py b/channels/telegram_channel.py
index 7f7c9be..0578d0e 100644
--- a/channels/telegram_channel.py
+++ b/channels/telegram_channel.py
@@ -22,10 +22,11 @@
 import asyncio
 import os
 import threading
-from typing import Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
 
 try:
     from telegram import Update
+    from telegram.constants import ParseMode
     from telegram.ext import (
         Application,
         CommandHandler,
@@ -33,7 +34,7 @@
         MessageHandler,
         filters,
     )
-    from telegram.constants import ParseMode
+
     TELEGRAM_AVAILABLE = True
 except ImportError:
     TELEGRAM_AVAILABLE = False
@@ -71,8 +72,14 @@ class TelegramChannel(Channel):
     the synchronous HTTP server.
     """
 
-    def __init__(self, bus: MessageBus, db: "TaskDB", scheduler: "TaskScheduler",
-                 token: str, allowed_users: Optional[list[int]] = None):
+    def __init__(
+        self,
+        bus: MessageBus,
+        db: "TaskDB",
+        scheduler: "TaskScheduler",
+        token: str,
+        allowed_users: Optional[list[int]] = None,
+    ):
         super().__init__("telegram", bus, db)
         self.scheduler = scheduler
         self._token = token
@@ -167,9 +174,15 @@ def send(self, msg: OutboundMessage) -> None:
         else:
             default_chat_id = self.db.get_setting("telegram_default_chat_id", "")
             if not default_chat_id:
-                print(f"[Telegram] No origin and no telegram_default_chat_id configured for task #{task_id}, skipping")
+                print(
+                    f"[Telegram] No origin and no telegram_default_chat_id configured for task #{task_id}, skipping"
+                )
                 return
-            chat_id = int(default_chat_id) if str(default_chat_id).lstrip("-").isdigit() else default_chat_id
+            chat_id = (
+                int(default_chat_id)
+                if str(default_chat_id).lstrip("-").isdigit()
+                else default_chat_id
+            )
             status_emoji = "✅" if is_completed else "❌"
             text = f"{status_emoji} Task #{task_id}: {title}\n{body}"
             if not is_completed:
@@ -184,6 +197,7 @@ async def _send_and_track():
                     emoji = "👍" if msg.type == OutboundMessageType.TASK_COMPLETED else "👎"
                     try:
                         from telegram import ReactionTypeEmoji
+
                         await self._app.bot.set_message_reaction(
                             chat_id=chat_id,
                             message_id=react_target,
@@ -193,13 +207,16 @@ async def _send_and_track():
                         print(f"[Telegram] Failed to set reaction on message {react_target}: {e}")
 
                 sent = await self._app.bot.send_message(
-                    chat_id=chat_id, text=text,
+                    chat_id=chat_id,
+                    text=text,
                     reply_to_message_id=orig_message_id,
                 )
                 if sent:
                     with self._notification_lock:
                         self._notification_map[sent.message_id] = task_id
-                    print(f"[Telegram] Notification msg_id={sent.message_id} mapped to task #{task_id}")
+                    print(
+                        f"[Telegram] Notification msg_id={sent.message_id} mapped to task #{task_id}"
+                    )
             except Exception as e:
                 print(f"[Telegram] Failed to send notification to {chat_id}: {e}")
 
@@ -227,8 +244,8 @@ async def _start_app(self) -> None:
         self._app = Application.builder().token(self._token).build()
 
         # Slash commands
-        self._app.add_handler(CommandHandler("start",  self._cmd_help))
-        self._app.add_handler(CommandHandler("help",   self._cmd_help))
+        self._app.add_handler(CommandHandler("start", self._cmd_help))
+        self._app.add_handler(CommandHandler("help", self._cmd_help))
         self._app.add_handler(CommandHandler("status", self._cmd_status))
         self._app.add_handler(CommandHandler("cancel", self._cmd_cancel))
         self._app.add_handler(CommandHandler("resume", self._cmd_resume))
@@ -308,6 +325,7 @@ def _format_forwarded_text(self, text: str, update: "Update") -> str:
         # 添加时间戳
         if msg.forward_date:
             from datetime import datetime
+
             ts = datetime.fromtimestamp(msg.forward_date)
             parts.append(f"时间: {ts.strftime('%Y-%m-%d %H:%M')}")
 
@@ -316,7 +334,9 @@ def _format_forwarded_text(self, text: str, update: "Update") -> str:
 
         return "\n".join(parts)
 
-    async def _handle_text_message(self, update: "Update", context: "ContextTypes.DEFAULT_TYPE") -> None:
+    async def _handle_text_message(
+        self, update: "Update", context: "ContextTypes.DEFAULT_TYPE"
+    ) -> None:
         """Handle any non-command text: resume-by-reply or create task."""
         if not self._is_allowed(update.effective_user.id):
             await update.message.reply_text("⛔ You are not authorised to use this bot.")
@@ -328,6 +348,7 @@ async def _handle_text_message(self, update: "Update", context: "ContextTypes.DE
 
         # ── /dir command: switch working directory ─────────────────
         from channels.dir_utils import handle_dir_command
+
         dir_reply = handle_dir_command(text, "telegram", self.db)
         if dir_reply is not None:
             await update.message.reply_text(dir_reply)
@@ -335,6 +356,7 @@ async def _handle_text_message(self, update: "Update", context: "ContextTypes.DE
 
         # ── /agent command: switch coding agent ──────────────────
         from channels.agent_utils import handle_agent_command
+
         agent_reply = handle_agent_command(text, "telegram", self.db)
         if agent_reply is not None:
             await update.message.reply_text(agent_reply)
@@ -362,11 +384,16 @@ async def _handle_text_message(self, update: "Update", context: "ContextTypes.DE
                         question=None,
                     )
                     with self._origin_lock:
-                        self._task_origin[task_id] = (chat_id, update.message.message_id, update.message.message_id)
+                        self._task_origin[task_id] = (
+                            chat_id,
+                            update.message.message_id,
+                            update.message.message_id,
+                        )
 
                     # Add "eyes" reaction and send resuming message
                     try:
                         from telegram import ReactionTypeEmoji
+
                         await self._app.bot.set_message_reaction(
                             chat_id=chat_id,
                             message_id=update.message.message_id,
@@ -388,7 +415,7 @@ async def _handle_text_message(self, update: "Update", context: "ContextTypes.DE
 
     def _create_task(self, text: str, chat_id: int, update: "Update") -> None:
         """Create a new task from any message text."""
-        from taskboard import Task, ScheduleType
+        from taskboard import ScheduleType, Task
 
         msg = update.message
 
@@ -398,9 +425,11 @@ def _create_task(self, text: str, chat_id: int, update: "Update") -> None:
         title = text[:60] + ("…" if len(text) > 60 else "")
 
         from channels.dir_utils import resolve_working_dir
+
         working_dir = resolve_working_dir(text, "telegram", self.db)
 
         from channels.agent_utils import resolve_agent
+
         task = Task(
             title=f"[Telegram] {title_prefix}{title}",
             prompt=text,
@@ -410,7 +439,9 @@ def _create_task(self, text: str, chat_id: int, update: "Update") -> None:
             agent=resolve_agent("telegram", self.db),
         )
         task_id = self.scheduler.submit_task(task)
-        print(f"[Telegram] Task #{task_id} created from message{' (forwarded)' if is_forwarded else ''}")
+        print(
+            f"[Telegram] Task #{task_id} created from message{' (forwarded)' if is_forwarded else ''}"
+        )
 
         message_id = update.message.message_id
         with self._origin_lock:
@@ -420,6 +451,7 @@ def _create_task(self, text: str, chat_id: int, update: "Update") -> None:
         async def _react():
             try:
                 from telegram import ReactionTypeEmoji
+
                 await self._app.bot.set_message_reaction(
                     chat_id=chat_id,
                     message_id=message_id,
@@ -459,8 +491,12 @@ async def _cmd_status(self, update: "Update", context: "ContextTypes.DEFAULT_TYP
             return
 
         status_icon = {
-            "pending": "🕐", "scheduled": "📅", "running": "⏳",
-            "completed": "✅", "failed": "❌", "cancelled": "🚫",
+            "pending": "🕐",
+            "scheduled": "📅",
+            "running": "⏳",
+            "completed": "✅",
+            "failed": "❌",
+            "cancelled": "🚫",
         }
         icon = status_icon.get(task["status"], "•")
         lines = [
@@ -491,9 +527,7 @@ async def _cmd_cancel(self, update: "Update", context: "ContextTypes.DEFAULT_TYP
             await update.message.reply_text(f"❌ Task #{task_id} not found.")
             return
         if task["status"] in ("completed", "failed", "cancelled"):
-            await update.message.reply_text(
-                f"ℹ️ Task #{task_id} is already {task['status']}."
-            )
+            await update.message.reply_text(f"ℹ️ Task #{task_id} is already {task['status']}.")
             return
 
         self.db.update_task(task_id, status="cancelled")
@@ -534,6 +568,7 @@ async def _cmd_resume(self, update: "Update", context: "ContextTypes.DEFAULT_TYP
         # Add "eyes" reaction to the user's command message
         try:
             from telegram import ReactionTypeEmoji
+
             await self._app.bot.set_message_reaction(
                 chat_id=chat_id,
                 message_id=update.message.message_id,
@@ -547,6 +582,7 @@ async def _cmd_resume(self, update: "Update", context: "ContextTypes.DEFAULT_TYP
 
 # ── helpers ──────────────────────────────────────────────────────────────────
 
+
 def _escape_md(text: str) -> str:
     """Escape special MarkdownV2 characters."""
     special = r"\_*[]()~`>#+-=|{}.!"
@@ -555,8 +591,10 @@ def _escape_md(text: str) -> str:
 
 # ── factory helper ───────────────────────────────────────────────────────────
 
-def create_telegram_channel(db, scheduler, bus=None,
-                            token: str = "", allowed_users_str: str = "") -> Optional["TelegramChannel"]:
+
+def create_telegram_channel(
+    db, scheduler, bus=None, token: str = "", allowed_users_str: str = ""
+) -> Optional["TelegramChannel"]:
     """Create a TelegramChannel from explicit params or environment variables."""
     token = (token or os.environ.get("TELEGRAM_BOT_TOKEN", "")).strip()
     if not token:
@@ -572,6 +610,7 @@ def create_telegram_channel(db, scheduler, bus=None,
 
     if bus is None:
         from taskboard_bus import MessageBus
+
         bus = MessageBus()
 
     return TelegramChannel(
diff --git a/docs/superpowers/plans/2026-03-18-backend-quality-baseline.md b/docs/superpowers/plans/2026-03-18-backend-quality-baseline.md
new file mode 100644
index 0000000..4b52a0f
--- /dev/null
+++ b/docs/superpowers/plans/2026-03-18-backend-quality-baseline.md
@@ -0,0 +1,72 @@
+# Backend Quality Baseline Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a sustainable Python backend quality baseline with Ruff linting/formatting, pytest coverage, and GitHub Actions CI gates.
+
+**Architecture:** Keep the current backend structure intact, add tool configuration centrally in `pyproject.toml`, and introduce a thin testable seam where needed. Build around the existing `tests/` suite instead of replacing it, then expose one local verification entrypoint through `Makefile` and reuse it in CI.
+
+**Tech Stack:** Python 3.12, uv, Ruff, pytest, pytest-cov, GitHub Actions
+
+---
+
+### Task 1: Baseline Audit And Tracking
+
+**Files:**
+- Modify: `docs/todo.md`
+- Create: `docs/superpowers/plans/2026-03-18-backend-quality-baseline.md`
+
+- [x] **Step 1: Record the work in project tracking**
+- [x] **Step 2: Save the implementation plan before code changes**
+
+### Task 2: Tooling Configuration
+
+**Files:**
+- Modify: `pyproject.toml`
+- Modify: `Makefile`
+
+- [ ] **Step 1: Add a failing lint/test entrypoint expectation**
+  - Run: `make check`
+  - Expected: fail because lint targets/config are missing
+- [ ] **Step 2: Add dev dependencies and tool config**
+  - Add `ruff` and `pytest-cov`
+  - Add `tool.ruff`, `tool.pytest.ini_options`, and coverage config
+- [ ] **Step 3: Add Makefile commands**
+  - Add `lint`, `format`, `format-check`, `test`, `test-cov`, `check`
+- [ ] **Step 4: Re-run focused verification**
+  - Run: `uv run ruff check .`
+  - Run: `uv run pytest`
+
+### Task 3: Test-First Coverage Fixes
+
+**Files:**
+- Modify: `tests/conftest.py`
+- Create or Modify: `tests/test_helpers.py`
+- Create or Modify: targeted backend tests as needed
+- Modify: backend Python files only when a failing test proves a seam is needed
+
+- [ ] **Step 1: Write or tighten one failing test at a time**
+  - Cover `_get_env()` and one database or scheduling seam
+- [ ] **Step 2: Run the focused test and confirm the failure is correct**
+- [ ] **Step 3: Make the minimal implementation/config change**
+- [ ] **Step 4: Re-run the focused test until green**
+
+### Task 4: CI Workflow
+
+**Files:**
+- Create: `.github/workflows/ci.yml`
+
+- [ ] **Step 1: Add CI for `pull_request` and `push` to `main`**
+- [ ] **Step 2: Install Python 3.12 and uv**
+- [ ] **Step 3: Run `uv sync --dev` and `make check`**
+- [ ] **Step 4: Confirm the workflow matches local verification commands**
+
+### Task 5: Final Verification And Tracking
+
+**Files:**
+- Modify: `docs/todo.md`
+
+- [ ] **Step 1: Run full project verification**
+  - Run: `make check`
+- [ ] **Step 2: Update tracking entry with completed status and evidence**
+- [ ] **Step 3: Summarize changes and any follow-up recommendations**
diff --git a/docs/todo.md b/docs/todo.md
index 8acea6f..2eb246e 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -2,6 +2,12 @@
 
 ## In Progress
 
+- [x] **建立后端 lint/test/CI 基线** — 为 Python 后端接入 `ruff`、`pytest` 覆盖率和 GitHub Actions 质量门禁
+  - ✅ 已完成：`pyproject.toml` 新增 `ruff` / `pytest-cov` 与 lint、pytest、coverage 配置
+  - ✅ 已完成：`Makefile` 新增 `lint` / `format` / `format-check` / `test` / `test-cov` / `check`
+  - ✅ 已完成：新增 `.github/workflows/ci.yml`，在 `pull_request` 和 `main` push 时执行 `make check`
+  - ✅ 已完成：补充 `tests/test_channel_utils.py` 和 `tests/test_taskboard_bus.py`，提升后端基线覆盖率
+  - ✅ 验证：`make check` 通过，`54 passed`，总覆盖率 `20.02%`
 - [x] **Install superpowers for Codex** — followed `https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md`
   - ✅ Cloned `obra/superpowers` to `~/.codex/superpowers`
   - ✅ Created `~/.agents/skills/superpowers` symlink to `~/.codex/superpowers/skills`
diff --git a/pyproject.toml b/pyproject.toml
index 22b0bec..20a022f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -21,4 +21,39 @@ dependencies = [
 dev = [
     "pyinstaller>=6.18.0",
     "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.11.0",
 ]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+extend-exclude = [
+    "skills",
+    "taskboard-electron",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-q"
+
+[tool.coverage.run]
+branch = true
+source = [
+    "taskboard",
+    "taskboard_bus",
+    "channels",
+]
+omit = [
+    "tests/*",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+fail_under = 20
diff --git a/skills/agentforge/scripts/agentforge_api.py b/skills/agentforge/scripts/agentforge_api.py
index f405377..1b660f5 100644
--- a/skills/agentforge/scripts/agentforge_api.py
+++ b/skills/agentforge/scripts/agentforge_api.py
@@ -31,14 +31,13 @@
 
 import argparse
 import json
-import sys
 import os
-import urllib.request
+import sys
 import urllib.error
 import urllib.parse
+import urllib.request
 from datetime import datetime
 
-
 API_BASE = "http://127.0.0.1:9712/api"
 
 SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
diff --git a/taskboard.py b/taskboard.py
index 86667cd..b17d9b2 100644
--- a/taskboard.py
+++ b/taskboard.py
@@ -3,25 +3,33 @@
 A kanban-style task board for orchestrating AI coding agents with cron scheduling and delayed execution.
 """
 
-import sqlite3
-import subprocess
 import json
-import threading
-import time
+import logging
 import os
+import secrets
 import signal
+import sqlite3
+import subprocess
 import sys
-import shutil
-import secrets
-import logging
+import threading
+import time
 from contextlib import contextmanager
+from dataclasses import dataclass, field
 from datetime import datetime, timedelta
-from dataclasses import dataclass, field, asdict
 from enum import Enum
-from typing import Optional, Callable
-from pathlib import Path
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Callable, Optional
+from urllib.parse import parse_qs, urlparse
+
 from croniter import croniter
 
+from taskboard_bus import (
+    BusAwareSchedulerMixin,
+    MessageBus,
+    OutboundMessageType,
+    UIChannel,
+)
+
 log_level = os.environ.get("AGENTFORGE_LOG_LEVEL", "INFO").upper()
 logging.basicConfig(
     level=getattr(logging, log_level, logging.INFO),
@@ -29,15 +37,10 @@
     datefmt="%Y-%m-%d %H:%M:%S",
 )
 logger = logging.getLogger("agentforge")
-from taskboard_bus import (
-    MessageBus,
-    BusAwareSchedulerMixin,
-    OutboundMessageType,
-    UIChannel,
-)
 
 try:
     from channels.feishu_channel import FeishuChannel
+
     FEISHU_CHANNEL_AVAILABLE = True
 except ImportError:
     FEISHU_CHANNEL_AVAILABLE = False
@@ -45,6 +48,7 @@
 
 try:
     from channels.telegram_channel import create_telegram_channel
+
     TELEGRAM_CHANNEL_AVAILABLE = True
 except ImportError:
     TELEGRAM_CHANNEL_AVAILABLE = False
@@ -52,6 +56,7 @@
 
 try:
     from channels.slack_channel import SlackChannel
+
     SLACK_CHANNEL_AVAILABLE = True
 except ImportError:
     SLACK_CHANNEL_AVAILABLE = False
@@ -60,6 +65,7 @@
 
 # ──────────────────────────── Helpers ────────────────────────────
 
+
 def _get_env() -> dict:
     """Return os.environ augmented with common macOS tool install paths.
     Electron (and other GUI launchers) inherit a stripped PATH that often
@@ -70,7 +76,7 @@ def _get_env() -> dict:
     extra = [
         f"{home}/.local/bin",
         "/usr/local/bin",
-        "/opt/homebrew/bin",       # Apple-silicon Homebrew
+        "/opt/homebrew/bin",  # Apple-silicon Homebrew
         "/usr/local/opt/node/bin",
         f"{home}/.npm/bin",
         f"{home}/.nvm/current/bin",
@@ -78,12 +84,15 @@ def _get_env() -> dict:
         "/bin",
     ]
     current = env.get("PATH", "")
-    env["PATH"] = ":".join(p for p in extra if p not in current) + (f":{current}" if current else "")
+    env["PATH"] = ":".join(p for p in extra if p not in current) + (
+        f":{current}" if current else ""
+    )
     return env
 
 
 # ──────────────────────────── Models ────────────────────────────
 
+
 class TaskStatus(str, Enum):
     PENDING = "pending"
     SCHEDULED = "scheduled"
@@ -91,14 +100,14 @@ class TaskStatus(str, Enum):
     COMPLETED = "completed"
     FAILED = "failed"
     CANCELLED = "cancelled"
-    BLOCKED = "blocked"          # has unmet upstream dependencies
+    BLOCKED = "blocked"  # has unmet upstream dependencies
 
 
 class ScheduleType(str, Enum):
     IMMEDIATE = "immediate"
-    DELAYED = "delayed"      # run after N seconds
+    DELAYED = "delayed"  # run after N seconds
     SCHEDULED_AT = "scheduled_at"  # run at a specific datetime
-    CRON = "cron"            # recurring cron expression
+    CRON = "cron"  # recurring cron expression
 
 
 class HeartbeatScheduleType(str, Enum):
@@ -122,24 +131,24 @@ class Task:
     working_dir: str = "."
     status: TaskStatus = TaskStatus.PENDING
     schedule_type: ScheduleType = ScheduleType.IMMEDIATE
-    cron_expr: Optional[str] = None          # e.g. "*/30 * * * *"
-    delay_seconds: Optional[int] = None      # e.g. 300
-    next_run_at: Optional[str] = None        # ISO timestamp
+    cron_expr: Optional[str] = None  # e.g. "*/30 * * * *"
+    delay_seconds: Optional[int] = None  # e.g. 300
+    next_run_at: Optional[str] = None  # ISO timestamp
     last_run_at: Optional[str] = None
     result: Optional[str] = None
     error: Optional[str] = None
     run_count: int = 0
-    max_runs: Optional[int] = None           # None = unlimited for cron
+    max_runs: Optional[int] = None  # None = unlimited for cron
     created_at: Optional[str] = None
     updated_at: Optional[str] = None
-    tags: str = ""                           # comma-separated
+    tags: str = ""  # comma-separated
     agent: str = "claude"
-    question: Optional[str] = None           # question the agent asked
-    answer: Optional[str] = None             # user's answer
-    session_id: Optional[str] = None         # claude session id for --resume
+    question: Optional[str] = None  # question the agent asked
+    answer: Optional[str] = None  # user's answer
+    session_id: Optional[str] = None  # claude session id for --resume
     prompt_images: list = field(default_factory=list)  # [{media_type, data, name}]
-    image_paths: list = field(default_factory=list)    # list of local image file paths
-    dag_id: Optional[str] = None             # optional DAG workflow group label
+    image_paths: list = field(default_factory=list)  # list of local image file paths
+    dag_id: Optional[str] = None  # optional DAG workflow group label
     feishu_root_msg_id: Optional[str] = None  # Feishu root message_id that created this task
 
 
@@ -168,6 +177,7 @@ class Heartbeat:
 
 # ──────────────────────────── Database ────────────────────────────
 
+
 class TaskDB:
     def __init__(self, db_path: str = "~/.agentforge/tasks.db"):
         self.db_path = os.path.expanduser(db_path)
@@ -409,21 +419,27 @@ def _init_db(self):
         # interrupted by a process kill (e.g. hot reload) and will never
         # self-transition to completed/failed without this reset.
         now = datetime.now().isoformat()
-        self.conn.execute("""
+        self.conn.execute(
+            """
             UPDATE tasks
             SET status = 'failed',
                 error  = 'Interrupted: process was restarted while task was running',
                 updated_at = ?
             WHERE status = 'running'
-        """, (now,))
+        """,
+            (now,),
+        )
         # Also close out any open task_runs rows that have no finished_at
-        self.conn.execute("""
+        self.conn.execute(
+            """
             UPDATE task_runs
             SET status = 'failed',
                 finished_at = ?,
                 error = 'Interrupted: process was restarted while task was running'
             WHERE finished_at IS NULL
-        """, (now,))
+        """,
+            (now,),
+        )
         self.conn.commit()
 
     @contextmanager
@@ -449,15 +465,32 @@ def add_task(self, task: Task) -> int:
             logger.debug(f"add_task called with image_paths: {task.image_paths}")
             image_paths_json = json.dumps(task.image_paths, ensure_ascii=False)
             logger.debug(f"image_paths JSON: {image_paths_json}")
-            cur = self.conn.execute("""
+            cur = self.conn.execute(
+                """
                 INSERT INTO tasks (title, prompt, working_dir, status, schedule_type,
                     cron_expr, delay_seconds, next_run_at, max_runs, created_at, updated_at, tags, agent, prompt_images, image_paths, dag_id, feishu_root_msg_id)
                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-            """, (task.title, task.prompt, task.working_dir, task.status.value,
-                  task.schedule_type.value, task.cron_expr, task.delay_seconds,
-                  task.next_run_at, task.max_runs, now, now, task.tags, task.agent,
-                  json.dumps(task.prompt_images, ensure_ascii=False),
-                  image_paths_json, task.dag_id, task.feishu_root_msg_id))
+            """,
+                (
+                    task.title,
+                    task.prompt,
+                    task.working_dir,
+                    task.status.value,
+                    task.schedule_type.value,
+                    task.cron_expr,
+                    task.delay_seconds,
+                    task.next_run_at,
+                    task.max_runs,
+                    now,
+                    now,
+                    task.tags,
+                    task.agent,
+                    json.dumps(task.prompt_images, ensure_ascii=False),
+                    image_paths_json,
+                    task.dag_id,
+                    task.feishu_root_msg_id,
+                ),
+            )
             self.conn.commit()
             task_id = cur.lastrowid
             logger.debug(f"Task {task_id} inserted with image_paths")
@@ -468,7 +501,7 @@ def get_task_by_feishu_root_msg(self, root_msg_id: str) -> Optional[dict]:
         with self.lock:
             row = self.conn.execute(
                 "SELECT * FROM tasks WHERE feishu_root_msg_id = ? ORDER BY id DESC LIMIT 1",
-                (root_msg_id,)
+                (root_msg_id,),
             ).fetchone()
             return dict(row) if row else None
 
@@ -480,8 +513,8 @@ def get_setting(self, key: str, default: str = None) -> Optional[str]:
     def set_setting(self, key: str, value: str):
         with self.lock:
             self.conn.execute(
-                "INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)",
-                (key, value))
+                "INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)", (key, value)
+            )
             self.conn.commit()
 
     def _deserialize_heartbeat(self, row) -> dict:
@@ -489,7 +522,9 @@ def _deserialize_heartbeat(self, row) -> dict:
         d["enabled"] = bool(d.get("enabled"))
         return d
 
-    def _compute_heartbeat_next_run_at(self, heartbeat: Heartbeat, now: Optional[datetime] = None) -> str:
+    def _compute_heartbeat_next_run_at(
+        self, heartbeat: Heartbeat, now: Optional[datetime] = None
+    ) -> str:
         now = now or datetime.now()
         if heartbeat.schedule_type == HeartbeatScheduleType.CRON:
             if not heartbeat.cron_expr:
@@ -505,8 +540,11 @@ def add_heartbeat(self, heartbeat: Heartbeat) -> int:
         with self.lock:
             now = datetime.now().isoformat()
             if heartbeat.next_run_at is None:
-                heartbeat.next_run_at = self._compute_heartbeat_next_run_at(heartbeat, datetime.now())
-            cur = self.conn.execute("""
+                heartbeat.next_run_at = self._compute_heartbeat_next_run_at(
+                    heartbeat, datetime.now()
+                )
+            cur = self.conn.execute(
+                """
                 INSERT INTO heartbeats (
                     name, enabled, working_dir, schedule_type, cron_expr,
                     interval_seconds, check_prompt, action_prompt_template,
@@ -514,36 +552,52 @@ def add_heartbeat(self, heartbeat: Heartbeat) -> int:
                     last_decision, last_error, last_triggered_at, last_dedupe_key,
                     created_at, updated_at
                 ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-            """, (
-                heartbeat.name,
-                1 if heartbeat.enabled else 0,
-                heartbeat.working_dir,
-                heartbeat.schedule_type.value,
-                heartbeat.cron_expr,
-                heartbeat.interval_seconds,
-                heartbeat.check_prompt,
-                heartbeat.action_prompt_template,
-                heartbeat.default_agent,
-                heartbeat.cooldown_seconds,
-                heartbeat.next_run_at,
-                heartbeat.last_tick_at,
-                heartbeat.last_decision,
-                heartbeat.last_error,
-                heartbeat.last_triggered_at,
-                heartbeat.last_dedupe_key,
-                now,
-                now,
-            ))
+            """,
+                (
+                    heartbeat.name,
+                    1 if heartbeat.enabled else 0,
+                    heartbeat.working_dir,
+                    heartbeat.schedule_type.value,
+                    heartbeat.cron_expr,
+                    heartbeat.interval_seconds,
+                    heartbeat.check_prompt,
+                    heartbeat.action_prompt_template,
+                    heartbeat.default_agent,
+                    heartbeat.cooldown_seconds,
+                    heartbeat.next_run_at,
+                    heartbeat.last_tick_at,
+                    heartbeat.last_decision,
+                    heartbeat.last_error,
+                    heartbeat.last_triggered_at,
+                    heartbeat.last_dedupe_key,
+                    now,
+                    now,
+                ),
+            )
             self.conn.commit()
             return cur.lastrowid
 
-    ALLOWED_HEARTBEAT_COLUMNS = frozenset({
-        "name", "enabled", "working_dir", "schedule_type", "cron_expr",
-        "interval_seconds", "check_prompt", "action_prompt_template",
-        "default_agent", "cooldown_seconds", "next_run_at", "last_tick_at",
-        "last_decision", "last_error", "last_triggered_at", "last_dedupe_key",
-        "updated_at",
-    })
+    ALLOWED_HEARTBEAT_COLUMNS = frozenset(
+        {
+            "name",
+            "enabled",
+            "working_dir",
+            "schedule_type",
+            "cron_expr",
+            "interval_seconds",
+            "check_prompt",
+            "action_prompt_template",
+            "default_agent",
+            "cooldown_seconds",
+            "next_run_at",
+            "last_tick_at",
+            "last_decision",
+            "last_error",
+            "last_triggered_at",
+            "last_dedupe_key",
+            "updated_at",
+        }
+    )
 
     def update_heartbeat(self, heartbeat_id: int, **kwargs):
         invalid = set(kwargs) - self.ALLOWED_HEARTBEAT_COLUMNS
@@ -558,7 +612,9 @@ def update_heartbeat(self, heartbeat_id: int, **kwargs):
 
     def get_heartbeat(self, heartbeat_id: int) -> Optional[dict]:
         with self.lock:
-            row = self.conn.execute("SELECT * FROM heartbeats WHERE id = ?", (heartbeat_id,)).fetchone()
+            row = self.conn.execute(
+                "SELECT * FROM heartbeats WHERE id = ?", (heartbeat_id,)
+            ).fetchone()
             return self._deserialize_heartbeat(row) if row else None
 
     def get_all_heartbeats(self) -> list[dict]:
@@ -569,12 +625,15 @@ def get_all_heartbeats(self) -> list[dict]:
     def get_due_heartbeats(self) -> list[dict]:
         now = datetime.now().isoformat()
         with self.lock:
-            rows = self.conn.execute("""
+            rows = self.conn.execute(
+                """
                 SELECT * FROM heartbeats
                 WHERE enabled = 1
                   AND next_run_at IS NOT NULL
                   AND next_run_at <= ?
-            """, (now,)).fetchall()
+            """,
+                (now,),
+            ).fetchall()
             return [self._deserialize_heartbeat(r) for r in rows]
 
     def delete_heartbeat(self, heartbeat_id: int):
@@ -585,88 +644,139 @@ def delete_heartbeat(self, heartbeat_id: int):
 
     def add_heartbeat_tick(self, heartbeat_id: int) -> int:
         with self.lock:
-            cur = self.conn.execute("""
+            cur = self.conn.execute(
+                """
                 INSERT INTO heartbeat_ticks (heartbeat_id, started_at, status)
                 VALUES (?, ?, 'running')
-            """, (heartbeat_id, datetime.now().isoformat()))
+            """,
+                (heartbeat_id, datetime.now().isoformat()),
+            )
             self.conn.commit()
             return cur.lastrowid
 
-    def finish_heartbeat_tick(self, tick_id: int, status: str, decision_type: Optional[str] = None,
-                              decision_payload: Optional[dict] = None, task_id: Optional[int] = None,
-                              raw_output: Optional[str] = None, error: Optional[str] = None):
-        payload_json = json.dumps(decision_payload, ensure_ascii=False) if decision_payload is not None else None
+    def finish_heartbeat_tick(
+        self,
+        tick_id: int,
+        status: str,
+        decision_type: Optional[str] = None,
+        decision_payload: Optional[dict] = None,
+        task_id: Optional[int] = None,
+        raw_output: Optional[str] = None,
+        error: Optional[str] = None,
+    ):
+        payload_json = (
+            json.dumps(decision_payload, ensure_ascii=False)
+            if decision_payload is not None
+            else None
+        )
         with self.lock:
-            self.conn.execute("""
+            self.conn.execute(
+                """
                 UPDATE heartbeat_ticks
                 SET finished_at = ?, status = ?, decision_type = ?, decision_payload = ?, task_id = ?, raw_output = ?, error = ?
                 WHERE id = ?
-            """, (
-                datetime.now().isoformat(),
-                status,
-                decision_type,
-                payload_json,
-                task_id,
-                raw_output,
-                error,
-                tick_id,
-            ))
+            """,
+                (
+                    datetime.now().isoformat(),
+                    status,
+                    decision_type,
+                    payload_json,
+                    task_id,
+                    raw_output,
+                    error,
+                    tick_id,
+                ),
+            )
             self.conn.commit()
 
     def get_heartbeat_ticks(self, heartbeat_id: int, limit: int = 50) -> list[dict]:
         with self.lock:
-            rows = self.conn.execute("""
+            rows = self.conn.execute(
+                """
                 SELECT * FROM heartbeat_ticks
                 WHERE heartbeat_id = ?
                 ORDER BY started_at DESC
                 LIMIT ?
-            """, (heartbeat_id, limit)).fetchall()
+            """,
+                (heartbeat_id, limit),
+            ).fetchall()
             return [dict(r) for r in rows]
 
     def get_heartbeat_tick(self, heartbeat_id: int, tick_id: int) -> Optional[dict]:
         with self.lock:
-            row = self.conn.execute("""
+            row = self.conn.execute(
+                """
                 SELECT * FROM heartbeat_ticks
                 WHERE heartbeat_id = ? AND id = ?
-            """, (heartbeat_id, tick_id)).fetchone()
+            """,
+                (heartbeat_id, tick_id),
+            ).fetchone()
             return dict(row) if row else None
 
     def get_latest_heartbeat_tick(self, heartbeat_id: int) -> Optional[dict]:
         with self.lock:
-            row = self.conn.execute("""
+            row = self.conn.execute(
+                """
                 SELECT * FROM heartbeat_ticks
                 WHERE heartbeat_id = ?
                 ORDER BY started_at DESC
                 LIMIT 1
-            """, (heartbeat_id,)).fetchone()
+            """,
+                (heartbeat_id,),
+            ).fetchone()
             return dict(row) if row else None
 
     def get_heartbeat_dedup(self, heartbeat_id: int, dedupe_key: str) -> Optional[dict]:
         with self.lock:
-            row = self.conn.execute("""
+            row = self.conn.execute(
+                """
                 SELECT * FROM heartbeat_dedup
                 WHERE heartbeat_id = ? AND dedupe_key = ?
-            """, (heartbeat_id, dedupe_key)).fetchone()
+            """,
+                (heartbeat_id, dedupe_key),
+            ).fetchone()
             return dict(row) if row else None
 
     def upsert_heartbeat_dedup(self, heartbeat_id: int, dedupe_key: str, task_id: Optional[int]):
         with self.lock:
             now = datetime.now().isoformat()
-            self.conn.execute("""
+            self.conn.execute(
+                """
                 INSERT INTO heartbeat_dedup (heartbeat_id, dedupe_key, task_id, triggered_at)
                 VALUES (?, ?, ?, ?)
                 ON CONFLICT(heartbeat_id, dedupe_key)
                 DO UPDATE SET task_id = excluded.task_id, triggered_at = excluded.triggered_at
-            """, (heartbeat_id, dedupe_key, task_id, now))
+            """,
+                (heartbeat_id, dedupe_key, task_id, now),
+            )
             self.conn.commit()
 
-    ALLOWED_TASK_COLUMNS = frozenset({
-        "title", "prompt", "working_dir", "status", "schedule_type",
-        "cron_expr", "delay_seconds", "next_run_at", "last_run_at",
-        "result", "error", "run_count", "max_runs",
-        "updated_at", "tags", "agent", "question", "answer",
-        "session_id", "prompt_images", "image_paths", "dag_id",
-    })
+    ALLOWED_TASK_COLUMNS = frozenset(
+        {
+            "title",
+            "prompt",
+            "working_dir",
+            "status",
+            "schedule_type",
+            "cron_expr",
+            "delay_seconds",
+            "next_run_at",
+            "last_run_at",
+            "result",
+            "error",
+            "run_count",
+            "max_runs",
+            "updated_at",
+            "tags",
+            "agent",
+            "question",
+            "answer",
+            "session_id",
+            "prompt_images",
+            "image_paths",
+            "dag_id",
+        }
+    )
 
     def update_task(self, task_id: int, **kwargs):
         invalid = set(kwargs) - self.ALLOWED_TASK_COLUMNS
@@ -714,90 +824,129 @@ def get_all_tasks(self) -> list[dict]:
     def get_due_tasks(self) -> list[dict]:
         now = datetime.now().isoformat()
         with self.lock:
-            rows = self.conn.execute("""
+            rows = self.conn.execute(
+                """
                 SELECT * FROM tasks
                 WHERE status IN ('pending', 'scheduled')
                   AND (next_run_at IS NULL OR next_run_at <= ?)
-            """, (now,)).fetchall()
+            """,
+                (now,),
+            ).fetchall()
             return [self._deserialize_task(r) for r in rows]
 
     def add_run(self, task_id: int) -> int:
         with self.lock:
             cur = self.conn.execute(
-                "INSERT INTO task_runs (task_id, status) VALUES (?, 'running')",
-                (task_id,))
+                "INSERT INTO task_runs (task_id, status) VALUES (?, 'running')", (task_id,)
+            )
             self.conn.commit()
             return cur.lastrowid
 
-    def finish_run(self, run_id: int, status: str, result: str = None, error: str = None, raw_output: str = None):
+    def finish_run(
+        self,
+        run_id: int,
+        status: str,
+        result: str = None,
+        error: str = None,
+        raw_output: str = None,
+    ):
         with self.lock:
-            self.conn.execute("""
+            self.conn.execute(
+                """
                 UPDATE task_runs SET finished_at = datetime('now'),
                     status = ?, result = ?, error = ?, raw_output = ?
                 WHERE id = ?
-            """, (status, result, error, raw_output, run_id))
+            """,
+                (status, result, error, raw_output, run_id),
+            )
             self.conn.commit()
 
-    def finish_run_and_update_task(self, run_id: int, run_status: str, task_id: int, task_updates: dict,
-                                   run_result: str = None, run_error: str = None, raw_output: str = None):
+    def finish_run_and_update_task(
+        self,
+        run_id: int,
+        run_status: str,
+        task_id: int,
+        task_updates: dict,
+        run_result: str = None,
+        run_error: str = None,
+        raw_output: str = None,
+    ):
         """Atomically finish a run record and update the parent task in one transaction."""
         task_updates = dict(task_updates)
         task_updates["updated_at"] = datetime.now().isoformat()
         sets = ", ".join(f"{k} = ?" for k in task_updates)
         vals = list(task_updates.values()) + [task_id]
         with self.transaction():
-            self.conn.execute("""
+            self.conn.execute(
+                """
                 UPDATE task_runs SET finished_at = datetime('now'),
                     status = ?, result = ?, error = ?, raw_output = ?
                 WHERE id = ?
-            """, (run_status, run_result, run_error, raw_output, run_id))
+            """,
+                (run_status, run_result, run_error, raw_output, run_id),
+            )
             self.conn.execute(f"UPDATE tasks SET {sets} WHERE id = ?", vals)
 
     def get_task_runs(self, task_id: int, limit: int = 20) -> list[dict]:
         with self.lock:
-            rows = self.conn.execute("""
+            rows = self.conn.execute(
+                """
                 SELECT * FROM task_runs WHERE task_id = ?
                 ORDER BY started_at DESC LIMIT ?
-            """, (task_id, limit)).fetchall()
+            """,
+                (task_id, limit),
+            ).fetchall()
             return [dict(r) for r in rows]
 
     def add_output_event(self, task_id: int, run_id: int, event_type: str, content: str):
         """Add a new output event to the database."""
         with self.lock:
-            self.conn.execute("""
+            self.conn.execute(
+                """
                 INSERT INTO task_output_events (task_id, run_id, event_type, content)
                 VALUES (?, ?, ?, ?)
-            """, (task_id, run_id, event_type, content))
+            """,
+                (task_id, run_id, event_type, content),
+            )
             self.conn.commit()
 
     def get_output_events(self, task_id: int, limit: int = 1000, offset: int = 0) -> list[dict]:
         """Get output events for a task, ordered by timestamp."""
         with self.lock:
-            rows = self.conn.execute("""
+            rows = self.conn.execute(
+                """
                 SELECT * FROM task_output_events
                 WHERE task_id = ?
                 ORDER BY timestamp DESC
                 LIMIT ? OFFSET ?
-            """, (task_id, limit, offset)).fetchall()
+            """,
+                (task_id, limit, offset),
+            ).fetchall()
             return [dict(r) for r in rows]
 
     def get_run_output_events(self, run_id: int, limit: int = 1000) -> list[dict]:
         """Get output events for a specific run."""
         with self.lock:
-            rows = self.conn.execute("""
+            rows = self.conn.execute(
+                """
                 SELECT * FROM task_output_events
                 WHERE run_id = ?
                 ORDER BY timestamp ASC
                 LIMIT ?
-            """, (run_id, limit)).fetchall()
+            """,
+                (run_id, limit),
+            ).fetchall()
             return [dict(r) for r in rows]
 
     def add_dependency(self, task_id: int, depends_on_task_id: int, inject_result: bool = False):
         with self.lock:
-            self.conn.execute("""
+            self.conn.execute(
+                """
                 INSERT OR IGNORE INTO task_dependencies (task_id, depends_on_task_id, inject_result)
                 VALUES (?, ?, ?)
-            """, (task_id, depends_on_task_id, 1 if inject_result else 0))
+            """,
+                (task_id, depends_on_task_id, 1 if inject_result else 0),
+            )
             self.conn.commit()
 
     def add_dependencies_batch(self, task_id: int, dep_list: list):
@@ -808,45 +957,56 @@ def add_dependencies_batch(self, task_id: int, dep_list: list):
         """
         with self.transaction():
             for dep in dep_list:
-                self.conn.execute("""
+                self.conn.execute(
+                    """
                     INSERT OR IGNORE INTO task_dependencies (task_id, depends_on_task_id, inject_result)
                     VALUES (?, ?, ?)
-                """, (task_id, dep["task_id"], 1 if dep["inject_result"] else 0))
+                """,
+                    (task_id, dep["task_id"], 1 if dep["inject_result"] else 0),
+                )
 
     def remove_dependency(self, task_id: int, depends_on_task_id: int):
         with self.lock:
-            self.conn.execute("""
+            self.conn.execute(
+                """
                 DELETE FROM task_dependencies WHERE task_id = ? AND depends_on_task_id = ?
-            """, (task_id, depends_on_task_id))
+            """,
+                (task_id, depends_on_task_id),
+            )
             self.conn.commit()
 
     def clear_dependencies(self, task_id: int):
         """Remove all upstream dependencies for a task."""
         with self.lock:
-            self.conn.execute(
-                "DELETE FROM task_dependencies WHERE task_id = ?", (task_id,))
+            self.conn.execute("DELETE FROM task_dependencies WHERE task_id = ?", (task_id,))
             self.conn.commit()
 
     def get_dependencies(self, task_id: int) -> list[dict]:
         """Return upstream tasks that task_id depends on."""
         with self.lock:
-            rows = self.conn.execute("""
+            rows = self.conn.execute(
+                """
                 SELECT td.*, t.title as depends_on_title, t.status as depends_on_status
                 FROM task_dependencies td
                 JOIN tasks t ON t.id = td.depends_on_task_id
                 WHERE td.task_id = ?
-            """, (task_id,)).fetchall()
+            """,
+                (task_id,),
+            ).fetchall()
             return [dict(r) for r in rows]
 
     def get_dependents(self, task_id: int) -> list[dict]:
         """Return downstream tasks that depend on task_id."""
         with self.lock:
-            rows = self.conn.execute("""
+            rows = self.conn.execute(
+                """
                 SELECT td.*, t.title as task_title, t.status as task_status
                 FROM task_dependencies td
                 JOIN tasks t ON t.id = td.task_id
                 WHERE td.depends_on_task_id = ?
-            """, (task_id,)).fetchall()
+            """,
+                (task_id,),
+            ).fetchall()
             return [dict(r) for r in rows]
 
     def get_dag_tasks(self, dag_id: str) -> list[dict]:
@@ -860,17 +1020,23 @@ def delete_task(self, task_id: int):
         with self.transaction():
             self.conn.execute("DELETE FROM task_output_events WHERE task_id = ?", (task_id,))
             self.conn.execute("DELETE FROM task_runs WHERE task_id = ?", (task_id,))
-            self.conn.execute("DELETE FROM task_dependencies WHERE task_id = ? OR depends_on_task_id = ?", (task_id, task_id))
+            self.conn.execute(
+                "DELETE FROM task_dependencies WHERE task_id = ? OR depends_on_task_id = ?",
+                (task_id, task_id),
+            )
             self.conn.execute("DELETE FROM tasks WHERE id = ?", (task_id,))
 
 
 # ──────────────────────────── Agent Executor ────────────────────────────
 
+
 class AgentExecutor:
     """Executes prompts via configurable AI agent CLIs."""
 
     @staticmethod
-    def run(prompt: str, working_dir: str = ".", timeout: int = 600, image_paths: list[str] = None) -> tuple[bool, str]:
+    def run(
+        prompt: str, working_dir: str = ".", timeout: int = 600, image_paths: list[str] = None
+    ) -> tuple[bool, str]:
         """
         Run a prompt through Claude Code CLI.
         Returns (success: bool, output: str)
@@ -889,7 +1055,15 @@ def run(prompt: str, working_dir: str = ".", timeout: int = 600, image_paths: li
                 for img_path in image_paths:
                     cmd.extend(["-i", img_path])
 
-            cmd.extend(["--output-format", "stream-json", "--verbose", "--permission-mode", "bypassPermissions"])
+            cmd.extend(
+                [
+                    "--output-format",
+                    "stream-json",
+                    "--verbose",
+                    "--permission-mode",
+                    "bypassPermissions",
+                ]
+            )
 
             result = subprocess.run(
                 cmd,
@@ -902,16 +1076,16 @@ def run(prompt: str, working_dir: str = ".", timeout: int = 600, image_paths: li
             if result.returncode == 0:
                 output = result.stdout
                 for line in reversed(result.stdout.splitlines()):
-                        line = line.strip()
-                        if not line:
-                            continue
-                        try:
-                            event = json.loads(line)
-                            if event.get("type") == "result":
-                                output = event.get("result", result.stdout)
-                                break
-                        except json.JSONDecodeError:
-                            pass
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        event = json.loads(line)
+                        if event.get("type") == "result":
+                            output = event.get("result", result.stdout)
+                            break
+                    except json.JSONDecodeError:
+                        pass
                 return True, output
             else:
                 return False, result.stderr or result.stdout
@@ -923,14 +1097,18 @@ def run(prompt: str, working_dir: str = ".", timeout: int = 600, image_paths: li
             return False, str(e)
 
 
-
 # ──────────────────────────── Scheduler ────────────────────────────
 
+
 class TaskScheduler(BusAwareSchedulerMixin):
     """Background scheduler that checks and runs due tasks."""
 
-    def __init__(self, db: TaskDB, on_task_update: Optional[Callable] = None,
-                 bus: Optional[MessageBus] = None):
+    def __init__(
+        self,
+        db: TaskDB,
+        on_task_update: Optional[Callable] = None,
+        bus: Optional[MessageBus] = None,
+    ):
         self.db = db
         self.executor = AgentExecutor()
         self.on_task_update = on_task_update
@@ -961,13 +1139,13 @@ def stop(self):
         running = {tid: t for tid, t in self._active_tasks.items() if t.is_alive()}
         if running:
             logger.info(f"Waiting for {len(running)} running task(s) to finish...")
-            for tid, t in running.items():
+            for _tid, t in running.items():
                 remaining = max(0, deadline - time.time())
                 t.join(timeout=remaining)
         heartbeat_running = {hid: t for hid, t in self._active_heartbeats.items() if t.is_alive()}
         if heartbeat_running:
             logger.info(f"Waiting for {len(heartbeat_running)} heartbeat(s) to finish...")
-            for hid, t in heartbeat_running.items():
+            for _hid, t in heartbeat_running.items():
                 remaining = max(0, deadline - time.time())
                 t.join(timeout=remaining)
         # Gracefully terminate any processes still alive, then force-kill if needed
@@ -1037,9 +1215,7 @@ def _tick(self):
     def _schedule_delayed(self, task: dict):
         delay = task.get("delay_seconds", 0) or 0
         run_at = datetime.now() + timedelta(seconds=delay)
-        self.db.update_task(task["id"],
-                            status="scheduled",
-                            next_run_at=run_at.isoformat())
+        self.db.update_task(task["id"], status="scheduled", next_run_at=run_at.isoformat())
         self._notify(task["id"])
 
     def _spawn_heartbeat(self, heartbeat: dict):
@@ -1075,11 +1251,13 @@ def _render_heartbeat_check_prompt(self, heartbeat: dict) -> str:
             heartbeat["check_prompt"],
         ]
         if heartbeat.get("action_prompt_template"):
-            lines.extend([
-                "",
-                "When decision is trigger_task, use this action prompt template as the base prompt to expand or adapt:",
-                heartbeat["action_prompt_template"],
-            ])
+            lines.extend(
+                [
+                    "",
+                    "When decision is trigger_task, use this action prompt template as the base prompt to expand or adapt:",
+                    heartbeat["action_prompt_template"],
+                ]
+            )
         return "\n".join(lines)
 
     def _parse_heartbeat_decision(self, raw_text: str) -> dict:
@@ -1091,7 +1269,7 @@ def _parse_heartbeat_decision(self, raw_text: str) -> dict:
             start = text.find("{")
             end = text.rfind("}")
             if start != -1 and end != -1 and end > start:
-                text = text[start:end + 1]
+                text = text[start : end + 1]
         payload = json.loads(text)
         decision = payload.get("decision")
         if decision not in {d.value for d in HeartbeatDecisionType}:
@@ -1112,25 +1290,36 @@ def _run_agent_prompt_once(self, agent: str, prompt: str, working_dir: str) -> t
         working_dir_expanded = os.path.expanduser(working_dir)
         if agent == "codex":
             cmd = [
-                "codex", "exec",
+                "codex",
+                "exec",
                 "--json",
                 "--dangerously-bypass-approvals-and-sandbox",
                 "--skip-git-repo-check",
-                "--cd", working_dir_expanded,
+                "--cd",
+                working_dir_expanded,
                 prompt,
             ]
         else:
             cmd = [
-                "claude", "-p", prompt,
-                "--output-format", "stream-json",
+                "claude",
+                "-p",
+                prompt,
+                "--output-format",
+                "stream-json",
                 "--verbose",
-                "--permission-mode", "bypassPermissions",
+                "--permission-mode",
+                "bypassPermissions",
             ]
         return self._run_agent_command(agent, cmd, working_dir_expanded)
 
-    def _run_agent_command(self, agent: str, cmd: list[str], working_dir_expanded: str,
-                           on_stdout_line: Optional[Callable[[str], None]] = None,
-                           on_stderr_line: Optional[Callable[[str], None]] = None) -> tuple[bool, str]:
+    def _run_agent_command(
+        self,
+        agent: str,
+        cmd: list[str],
+        working_dir_expanded: str,
+        on_stdout_line: Optional[Callable[[str], None]] = None,
+        on_stderr_line: Optional[Callable[[str], None]] = None,
+    ) -> tuple[bool, str]:
         try:
             proc = subprocess.Popen(
                 cmd,
@@ -1194,8 +1383,10 @@ def _read_stream(stream, chunks, callback):
                     event = json.loads(line)
                 except json.JSONDecodeError:
                     continue
-                if (event.get("type") == "item.completed"
-                        and event.get("item", {}).get("type") == "agent_message"):
+                if (
+                    event.get("type") == "item.completed"
+                    and event.get("item", {}).get("type") == "agent_message"
+                ):
                     out = event["item"].get("text", "")
             return True, out or raw_stdout
 
@@ -1271,6 +1462,7 @@ def _execute_heartbeat(self, heartbeat: dict):
             now,
         )
         try:
+
             def _append_tick_output(line: str):
                 output_chunks.append(line)
                 self._live_heartbeat_output[tick_id] = "".join(output_chunks)
@@ -1280,19 +1472,25 @@ def _append_tick_output(line: str):
             working_dir_expanded = os.path.expanduser(heartbeat["working_dir"])
             if agent == "codex":
                 cmd = [
-                    "codex", "exec",
+                    "codex",
+                    "exec",
                     "--json",
                     "--dangerously-bypass-approvals-and-sandbox",
                     "--skip-git-repo-check",
-                    "--cd", working_dir_expanded,
+                    "--cd",
+                    working_dir_expanded,
                     prompt,
                 ]
             else:
                 cmd = [
-                    "claude", "-p", prompt,
-                    "--output-format", "stream-json",
+                    "claude",
+                    "-p",
+                    prompt,
+                    "--output-format",
+                    "stream-json",
                     "--verbose",
-                    "--permission-mode", "bypassPermissions",
+                    "--permission-mode",
+                    "bypassPermissions",
                 ]
             success, raw_output = self._run_agent_command(
                 agent,
@@ -1310,9 +1508,15 @@ def _append_tick_output(line: str):
                 if self._heartbeat_trigger_suppressed(heartbeat, dedupe_key):
                     decision_type = HeartbeatDecisionType.IDLE.value
                     decision["decision"] = decision_type
-                    decision["reason"] = "Suppressed duplicate signal during cooldown or while prior task is still active"
+                    decision["reason"] = (
+                        "Suppressed duplicate signal during cooldown or while prior task is still active"
+                    )
                 else:
-                    task_prompt = decision.get("prompt") or heartbeat.get("action_prompt_template") or heartbeat["check_prompt"]
+                    task_prompt = (
+                        decision.get("prompt")
+                        or heartbeat.get("action_prompt_template")
+                        or heartbeat["check_prompt"]
+                    )
                     task_title = decision.get("title") or f"Heartbeat: {heartbeat['name']}"
                     task = Task(
                         title=task_title,
@@ -1353,7 +1557,9 @@ def _append_tick_output(line: str):
             )
             self.db.finish_heartbeat_tick(
                 tick_id,
-                status="idle" if decision_type == HeartbeatDecisionType.IDLE.value else decision_type,
+                status="idle"
+                if decision_type == HeartbeatDecisionType.IDLE.value
+                else decision_type,
                 decision_type=decision_type,
                 decision_payload=decision,
                 raw_output=("".join(output_chunks)[:500000] if output_chunks else None),
@@ -1395,7 +1601,9 @@ def _parse_codex_event(self, event: dict) -> tuple:
             elif itype == "command_execution":
                 cmd = item.get("command", "")
                 out = item.get("aggregated_output", "")
-                content = f"$ {cmd}\n{out}".strip() if cmd else json.dumps(event, ensure_ascii=False)
+                content = (
+                    f"$ {cmd}\n{out}".strip() if cmd else json.dumps(event, ensure_ascii=False)
+                )
                 return etype, content
             else:
                 return etype, json.dumps(event, ensure_ascii=False)
@@ -1472,10 +1680,13 @@ def _extract_message_content(self, event: dict) -> tuple:
                 elif item.get("type") == "image":
                     source = item.get("source", {})
                     if source.get("type") == "base64":
-                        img_json = json.dumps({
-                            "media_type": source.get("media_type", "image/jpeg"),
-                            "data": source.get("data", ""),
-                        }, ensure_ascii=False)
+                        img_json = json.dumps(
+                            {
+                                "media_type": source.get("media_type", "image/jpeg"),
+                                "data": source.get("data", ""),
+                            },
+                            ensure_ascii=False,
+                        )
                         image_events.append(img_json)
                     # Non-base64 image sources (url, etc.) are ignored silently
 
@@ -1489,8 +1700,8 @@ def _extract_error_summary(self, raw_stderr: str, raw_stdout: str) -> str:
         """
         # If stderr is short and not JSON, it's likely a plain error message
         if raw_stderr and len(raw_stderr) < 2000:
-            first_line = raw_stderr.strip().split('\n')[0].strip()
-            if first_line and not first_line.startswith('{'):
+            first_line = raw_stderr.strip().split("\n")[0].strip()
+            if first_line and not first_line.startswith("{"):
                 return raw_stderr.strip()[:1000]
 
         # Try to parse stdout as stream-json to find error events
@@ -1574,7 +1785,9 @@ def _is_safe_image_path(path: str) -> bool:
 
             for img_path in image_paths:
                 if not _is_safe_image_path(img_path):
-                    logger.warning(f"Task {tid}: Rejected image path outside allowed directories: {img_path}")
+                    logger.warning(
+                        f"Task {tid}: Rejected image path outside allowed directories: {img_path}"
+                    )
                     continue
                 try:
                     with open(img_path, "rb") as f:
@@ -1594,23 +1807,27 @@ def _is_safe_image_path(path: str) -> bool:
                         # Try to detect from magic bytes
                         with open(img_path, "rb") as f:
                             header = f.read(12)
-                        if header.startswith(b'\xff\xd8\xff'):
+                        if header.startswith(b"\xff\xd8\xff"):
                             media_type = "image/jpeg"
-                        elif header.startswith(b'\x89PNG\r\n\x1a\n'):
+                        elif header.startswith(b"\x89PNG\r\n\x1a\n"):
                             media_type = "image/png"
-                        elif header.startswith(b'GIF87a') or header.startswith(b'GIF89a'):
+                        elif header.startswith(b"GIF87a") or header.startswith(b"GIF89a"):
                             media_type = "image/gif"
-                        elif header.startswith(b'RIFF') and b'WEBP' in header:
+                        elif header.startswith(b"RIFF") and b"WEBP" in header:
                             media_type = "image/webp"
                         else:
                             media_type = "image/jpeg"  # default fallback
 
-                    prompt_images.append({
-                        "media_type": media_type,
-                        "data": img_data,
-                        "name": os.path.basename(img_path)
-                    })
-                    logger.debug(f"Task {tid}: Loaded image {img_path} as {media_type} ({len(img_data)} bytes base64)")
+                    prompt_images.append(
+                        {
+                            "media_type": media_type,
+                            "data": img_data,
+                            "name": os.path.basename(img_path),
+                        }
+                    )
+                    logger.debug(
+                        f"Task {tid}: Loaded image {img_path} as {media_type} ({len(img_data)} bytes base64)"
+                    )
                 except Exception as e:
                     logger.error(f"Task {tid}: Failed to load image {img_path}: {e}")
 
@@ -1621,7 +1838,9 @@ def _is_safe_image_path(path: str) -> bool:
             working_dir_expanded = os.path.expanduser(task["working_dir"])
             if task.get("session_id"):
                 cmd = [
-                    "codex", "exec", "resume",
+                    "codex",
+                    "exec",
+                    "resume",
                     "--json",
                     "--dangerously-bypass-approvals-and-sandbox",
                     "--skip-git-repo-check",
@@ -1630,23 +1849,41 @@ def _is_safe_image_path(path: str) -> bool:
                 ]
             else:
                 cmd = [
-                    "codex", "exec",
+                    "codex",
+                    "exec",
                     "--json",
                     "--dangerously-bypass-approvals-and-sandbox",
                     "--skip-git-repo-check",
-                    "--cd", working_dir_expanded,
+                    "--cd",
+                    working_dir_expanded,
                     prompt,
                 ]
             for img_path in image_paths or []:
                 cmd.extend(["--image", img_path])
         elif use_stdin:
             # Claude multimodal input: pass via stdin with --input-format stream-json
-            cmd = ["claude", "-p", "--input-format", "stream-json",
-                   "--output-format", "stream-json", "--verbose",
-                   "--permission-mode", "bypassPermissions"]
+            cmd = [
+                "claude",
+                "-p",
+                "--input-format",
+                "stream-json",
+                "--output-format",
+                "stream-json",
+                "--verbose",
+                "--permission-mode",
+                "bypassPermissions",
+            ]
         else:
-            cmd = ["claude", "-p", prompt, "--output-format", "stream-json",
-                   "--verbose", "--permission-mode", "bypassPermissions"]
+            cmd = [
+                "claude",
+                "-p",
+                prompt,
+                "--output-format",
+                "stream-json",
+                "--verbose",
+                "--permission-mode",
+                "bypassPermissions",
+            ]
         if agent == "claude" and task.get("session_id"):
             cmd.extend(["--resume", task["session_id"]])
         raw_stdout = ""
@@ -1668,18 +1905,19 @@ def _is_safe_image_path(path: str) -> bool:
                 # Build multimodal message content
                 content = [{"type": "text", "text": prompt}]
                 for img in prompt_images:
-                    content.append({
-                        "type": "image",
-                        "source": {
-                            "type": "base64",
-                            "media_type": img.get("media_type", "image/jpeg"),
-                            "data": img.get("data", ""),
+                    content.append(
+                        {
+                            "type": "image",
+                            "source": {
+                                "type": "base64",
+                                "media_type": img.get("media_type", "image/jpeg"),
+                                "data": img.get("data", ""),
+                            },
                         }
-                    })
-                stdin_msg = json.dumps({
-                    "type": "user",
-                    "message": {"role": "user", "content": content}
-                })
+                    )
+                stdin_msg = json.dumps(
+                    {"type": "user", "message": {"role": "user", "content": content}}
+                )
                 proc.stdin.write(stdin_msg + "\n")
                 proc.stdin.close()
             pgid = os.getpgid(proc.pid)
@@ -1687,24 +1925,30 @@ def _is_safe_image_path(path: str) -> bool:
 
             # Read stderr in a background thread so it never blocks stdout reading
             stderr_chunks = []
+
             def _read_stderr():
                 for line in proc.stderr:
                     stderr_chunks.append(line)
+
             stderr_thread = threading.Thread(target=_read_stderr, daemon=True)
             stderr_thread.start()
 
             # Timer that kills the entire process group if it exceeds the configured timeout
             timed_out = [False]
+
             def _kill():
                 timed_out[0] = True
                 try:
                     os.killpg(pgid, signal.SIGKILL)
                 except OSError as e:
-                    logger.error(f"Task {tid}: killpg({pgid}) failed: {e}, falling back to kill({proc.pid})")
+                    logger.error(
+                        f"Task {tid}: killpg({pgid}) failed: {e}, falling back to kill({proc.pid})"
+                    )
                     try:
                         os.kill(proc.pid, signal.SIGKILL)
                     except OSError as e2:
                         logger.error(f"Task {tid}: kill({proc.pid}) also failed: {e2}")
+
             timer = threading.Timer(timeout_secs, _kill)
             timer.start()
 
@@ -1735,7 +1979,9 @@ def _kill():
                     if not waiting_logged:
                         waiting_logged = True
                         logger.info(f"Task {tid}: main process exited, waiting for sub-agents...")
-                    self._live_output[tid] = "".join(chunks) + "\n[⏳ Waiting for sub-agents to complete...]"
+                    self._live_output[tid] = (
+                        "".join(chunks) + "\n[⏳ Waiting for sub-agents to complete...]"
+                    )
                     time.sleep(1)
                 else:
                     # Sub-agents exceeded remaining timeout — kill the group
@@ -1762,8 +2008,10 @@ def _kill():
                             continue
                         try:
                             event = json.loads(line)
-                            if (event.get("type") == "item.completed"
-                                    and event.get("item", {}).get("type") == "agent_message"):
+                            if (
+                                event.get("type") == "item.completed"
+                                and event.get("item", {}).get("type") == "agent_message"
+                            ):
                                 out = event["item"].get("text", "")
                         except json.JSONDecodeError:
                             pass
@@ -1804,7 +2052,11 @@ def _kill():
                 success, output = False, raw_stderr or raw_stdout
         except FileNotFoundError:
             cli_name = "codex" if task.get("agent") == "codex" else "claude"
-            install_hint = "Install with: npm install -g @openai/codex" if cli_name == "codex" else "Is it installed?"
+            install_hint = (
+                "Install with: npm install -g @openai/codex"
+                if cli_name == "codex"
+                else "Is it installed?"
+            )
             success, output = False, f"{cli_name} CLI not found. {install_hint}"
             self._active_pgids.pop(tid, None)
         except (OSError, subprocess.SubprocessError) as e:
@@ -1868,8 +2120,9 @@ def _kill():
                     cron_will_reschedule = True
             else:
                 updates["status"] = "completed"
-            self.db.finish_run_and_update_task(run_id, "completed", tid, updates,
-                                               run_result=output, raw_output=raw_output_stored)
+            self.db.finish_run_and_update_task(
+                run_id, "completed", tid, updates, run_result=output, raw_output=raw_output_stored
+            )
             # For cron tasks that get rescheduled, notify channels with TASK_COMPLETED
             # before the status flips to "scheduled", so channels actually fire.
             if cron_will_reschedule:
@@ -1877,18 +2130,23 @@ def _kill():
         else:
             # Extract a clean, human-readable error summary for task.error and
             # notification channels. The full raw output is preserved in run_error.
-            error_summary = self._extract_error_summary(raw_stderr, raw_stdout) if (
-                raw_stderr or raw_stdout
-            ) else (output or "Unknown error")
+            error_summary = (
+                self._extract_error_summary(raw_stderr, raw_stdout)
+                if (raw_stderr or raw_stdout)
+                else (output or "Unknown error")
+            )
             self.db.finish_run_and_update_task(
-                run_id, "failed", tid,
+                run_id,
+                "failed",
+                tid,
                 {
                     "status": "failed",
                     "error": error_summary,
                     "last_run_at": datetime.now().isoformat(),
                     "run_count": new_count,
                 },
-                run_error=output, raw_output=raw_output_stored,
+                run_error=output,
+                raw_output=raw_output_stored,
             )
 
         self._notify(tid)
@@ -1927,10 +2185,12 @@ def submit_task(self, task: Task, depends_on: list = None) -> int:
                 if isinstance(dep, int):
                     dep_list.append({"task_id": dep, "inject_result": False})
                 elif isinstance(dep, dict):
-                    dep_list.append({
-                        "task_id": dep["task_id"],
-                        "inject_result": bool(dep.get("inject_result", False)),
-                    })
+                    dep_list.append(
+                        {
+                            "task_id": dep["task_id"],
+                            "inject_result": bool(dep.get("inject_result", False)),
+                        }
+                    )
 
         # Determine initial status: BLOCKED if any upstream not completed
         has_unmet = False
@@ -2037,7 +2297,9 @@ def _on_task_failed(self, task_id: int):
                 status="cancelled",
                 error=f"Cancelled: upstream task #{origin_id} failed",
             )
-            logger.info(f"DAG: Task {downstream_id} cascade-cancelled (upstream #{origin_id} failed)")
+            logger.info(
+                f"DAG: Task {downstream_id} cascade-cancelled (upstream #{origin_id} failed)"
+            )
             self._notify(downstream_id)
 
     # ─────────────────────────────────────────────────────────────
@@ -2060,7 +2322,10 @@ def trigger_heartbeat_now(self, heartbeat_id: int):
         heartbeat = self.db.get_heartbeat(heartbeat_id)
         if not heartbeat:
             raise ValueError("heartbeat not found")
-        if heartbeat_id in self._active_heartbeats and self._active_heartbeats[heartbeat_id].is_alive():
+        if (
+            heartbeat_id in self._active_heartbeats
+            and self._active_heartbeats[heartbeat_id].is_alive()
+        ):
             raise ValueError("heartbeat already running")
         self._spawn_heartbeat(heartbeat)
 
@@ -2094,11 +2359,6 @@ def resume_heartbeat(self, heartbeat_id: int):
 
 
 # ──────────────────────────── HTTP API Server ────────────────────────────
-
-from http.server import HTTPServer, BaseHTTPRequestHandler
-from urllib.parse import urlparse, parse_qs
-import json
-
 # Single CSRF token for the lifetime of this server process.
 # The frontend fetches it once via GET /api/csrf-token and includes it as
 # the X-CSRF-Token header on all state-changing requests.
@@ -2129,7 +2389,9 @@ def do_OPTIONS(self):
         self._cors_headers()
         self.end_headers()
 
-    def _validate_heartbeat_payload(self, body: dict, existing: Optional[dict] = None) -> tuple[Optional[Heartbeat], Optional[tuple[dict, int]]]:
+    def _validate_heartbeat_payload(
+        self, body: dict, existing: Optional[dict] = None
+    ) -> tuple[Optional[Heartbeat], Optional[tuple[dict, int]]]:
         def _coerce_bool(value):
             if isinstance(value, bool):
                 return value
@@ -2146,50 +2408,106 @@ def _coerce_bool(value):
         if working_dir and working_dir != ".":
             expanded = os.path.expanduser(working_dir)
             if not os.path.isdir(expanded):
-                return None, ({"error": f"working_dir does not exist or is not a directory: {working_dir}", "field": "working_dir"}, 400)
+                return None, (
+                    {
+                        "error": f"working_dir does not exist or is not a directory: {working_dir}",
+                        "field": "working_dir",
+                    },
+                    400,
+                )
 
-        schedule_value = body.get("schedule_type", existing.get("schedule_type") if existing else "interval")
+        schedule_value = body.get(
+            "schedule_type", existing.get("schedule_type") if existing else "interval"
+        )
         try:
             schedule_type = HeartbeatScheduleType(schedule_value)
         except ValueError:
-            return None, ({"error": f"invalid heartbeat schedule_type: {schedule_value}", "field": "schedule_type"}, 400)
+            return None, (
+                {
+                    "error": f"invalid heartbeat schedule_type: {schedule_value}",
+                    "field": "schedule_type",
+                },
+                400,
+            )
 
         cron_expr = body.get("cron_expr", existing.get("cron_expr") if existing else None)
-        interval_seconds = body.get("interval_seconds", existing.get("interval_seconds") if existing else None)
+        interval_seconds = body.get(
+            "interval_seconds", existing.get("interval_seconds") if existing else None
+        )
         if schedule_type == HeartbeatScheduleType.CRON:
             if not cron_expr or not str(cron_expr).strip():
-                return None, ({"error": "cron_expr is required for cron heartbeat", "field": "cron_expr"}, 400)
+                return None, (
+                    {"error": "cron_expr is required for cron heartbeat", "field": "cron_expr"},
+                    400,
+                )
             if not croniter.is_valid(cron_expr):
-                return None, ({"error": f"invalid cron expression: {cron_expr}", "field": "cron_expr"}, 400)
+                return None, (
+                    {"error": f"invalid cron expression: {cron_expr}", "field": "cron_expr"},
+                    400,
+                )
             interval_seconds = None
         else:
             try:
                 interval_seconds = int(interval_seconds)
             except (TypeError, ValueError):
-                return None, ({"error": "interval_seconds must be a positive integer", "field": "interval_seconds"}, 400)
+                return None, (
+                    {
+                        "error": "interval_seconds must be a positive integer",
+                        "field": "interval_seconds",
+                    },
+                    400,
+                )
             if interval_seconds <= 0:
-                return None, ({"error": "interval_seconds must be a positive integer", "field": "interval_seconds"}, 400)
+                return None, (
+                    {
+                        "error": "interval_seconds must be a positive integer",
+                        "field": "interval_seconds",
+                    },
+                    400,
+                )
             cron_expr = None
 
-        cooldown_seconds = body.get("cooldown_seconds", existing.get("cooldown_seconds") if existing else 0)
+        cooldown_seconds = body.get(
+            "cooldown_seconds", existing.get("cooldown_seconds") if existing else 0
+        )
         try:
             cooldown_seconds = int(cooldown_seconds or 0)
         except (TypeError, ValueError):
-            return None, ({"error": "cooldown_seconds must be an integer", "field": "cooldown_seconds"}, 400)
+            return None, (
+                {"error": "cooldown_seconds must be an integer", "field": "cooldown_seconds"},
+                400,
+            )
         if cooldown_seconds < 0:
-            return None, ({"error": "cooldown_seconds cannot be negative", "field": "cooldown_seconds"}, 400)
+            return None, (
+                {"error": "cooldown_seconds cannot be negative", "field": "cooldown_seconds"},
+                400,
+            )
 
         heartbeat = Heartbeat(
             id=existing.get("id") if existing else None,
             name=name,
-            enabled=_coerce_bool(body.get("enabled", existing.get("enabled") if existing else True)),
+            enabled=_coerce_bool(
+                body.get("enabled", existing.get("enabled") if existing else True)
+            ),
             working_dir=working_dir,
             schedule_type=schedule_type,
             cron_expr=cron_expr,
             interval_seconds=interval_seconds,
             check_prompt=str(check_prompt),
-            action_prompt_template=str(body.get("action_prompt_template", existing.get("action_prompt_template") if existing else "")),
-            default_agent=str(body.get("default_agent", existing.get("default_agent") if existing else self.db.get_setting("default_agent", "claude"))),
+            action_prompt_template=str(
+                body.get(
+                    "action_prompt_template",
+                    existing.get("action_prompt_template") if existing else "",
+                )
+            ),
+            default_agent=str(
+                body.get(
+                    "default_agent",
+                    existing.get("default_agent")
+                    if existing
+                    else self.db.get_setting("default_agent", "claude"),
+                )
+            ),
             cooldown_seconds=cooldown_seconds,
             next_run_at=existing.get("next_run_at") if existing else None,
             last_tick_at=existing.get("last_tick_at") if existing else None,
@@ -2217,7 +2535,9 @@ def do_GET(self):
                 self._json_response({"error": "not found"}, 404)
                 return
             live = self.scheduler._live_heartbeat_output.get(tick_id, tick.get("raw_output") or "")
-            self._json_response({"output": live, "is_running": tick_id in self.scheduler._live_heartbeat_output})
+            self._json_response(
+                {"output": live, "is_running": tick_id in self.scheduler._live_heartbeat_output}
+            )
 
         elif path.startswith("/api/heartbeats/") and path.endswith("/ticks"):
             hid = int(path.split("/")[3])
@@ -2284,7 +2604,9 @@ def do_GET(self):
                                 elif isinstance(c, str):
                                     text += c
                             if text.strip():
-                                run_messages.append({"role": "user", "text": text, "run_id": run["id"]})
+                                run_messages.append(
+                                    {"role": "user", "text": text, "run_id": run["id"]}
+                                )
                         elif etype == "assistant":
                             msg = event.get("message", {})
                             content = msg.get("content", [])
@@ -2293,7 +2615,9 @@ def do_GET(self):
                                 if isinstance(c, dict) and c.get("type") == "text":
                                     text += c.get("text", "")
                             if text.strip():
-                                run_messages.append({"role": "assistant", "text": text, "run_id": run["id"]})
+                                run_messages.append(
+                                    {"role": "assistant", "text": text, "run_id": run["id"]}
+                                )
                     except json.JSONDecodeError:
                         pass
                 messages.extend(run_messages)
@@ -2308,7 +2632,7 @@ def do_GET(self):
             self._json_response(self.db.get_dependents(tid))
 
         elif path.startswith("/api/dag/"):
-            dag_id = path[len("/api/dag/"):]
+            dag_id = path[len("/api/dag/") :]
             tasks = self.db.get_dag_tasks(dag_id)
             for t in tasks:
                 t["dependencies"] = self.db.get_dependencies(t["id"])
@@ -2332,48 +2656,74 @@ def do_GET(self):
             self._json_response({"status": "ok", "tasks": len(self.db.get_all_tasks())})
 
         elif path == "/api/settings":
-            self._json_response({
-                "default_agent": self.db.get_setting("default_agent", "claude"),
-                "timeout": int(self.db.get_setting("timeout", "600")),
-            })
+            self._json_response(
+                {
+                    "default_agent": self.db.get_setting("default_agent", "claude"),
+                    "timeout": int(self.db.get_setting("timeout", "600")),
+                }
+            )
 
         elif path == "/api/feishu/settings":
-            self._json_response({
-                "feishu_app_id": self.db.get_setting("feishu_app_id", ""),
-                "feishu_app_secret": self.db.get_setting("feishu_app_secret", ""),
-                "feishu_default_chat_id": self.db.get_setting("feishu_default_chat_id", ""),
-                "feishu_default_working_dir": self.db.get_setting("feishu_default_working_dir", "~"),
-                "feishu_enabled": self.db.get_setting("feishu_enabled", "false"),
-            })
+            self._json_response(
+                {
+                    "feishu_app_id": self.db.get_setting("feishu_app_id", ""),
+                    "feishu_app_secret": self.db.get_setting("feishu_app_secret", ""),
+                    "feishu_default_chat_id": self.db.get_setting("feishu_default_chat_id", ""),
+                    "feishu_default_working_dir": self.db.get_setting(
+                        "feishu_default_working_dir", "~"
+                    ),
+                    "feishu_enabled": self.db.get_setting("feishu_enabled", "false"),
+                }
+            )
 
         elif path == "/api/channels/status":
             import os as _os
+
             # Tokens can come from settings DB or env vars
-            tg_token = self.db.get_setting("telegram_bot_token", "") or _os.environ.get("TELEGRAM_BOT_TOKEN", "")
-            sl_bot = self.db.get_setting("slack_bot_token", "") or _os.environ.get("SLACK_BOT_TOKEN", "")
-            sl_app = self.db.get_setting("slack_app_token", "") or _os.environ.get("SLACK_APP_TOKEN", "")
-            self._json_response({
-                "telegram": {
-                    "enabled": self.db.get_setting("telegram_enabled", "false") == "true",
-                    "configured": bool(tg_token),
-                    "running": bool(self.telegram_channel and getattr(self.telegram_channel, "_running", False)),
-                    "default_working_dir": self.db.get_setting("telegram_default_working_dir", "~"),
-                    "default_chat_id": self.db.get_setting("telegram_default_chat_id", ""),
-                    "allowed_users": self.db.get_setting("telegram_allowed_users", ""),
-                },
-                "slack": {
-                    "enabled": self.db.get_setting("slack_enabled", "false") == "true",
-                    "configured": bool(sl_bot and sl_app),
-                    "running": bool(self.slack_channel and getattr(self.slack_channel, "_running", False)),
-                    "default_working_dir": self.db.get_setting("slack_default_working_dir", "~"),
-                    "default_channel": self.db.get_setting("slack_default_channel", ""),
-                    "default_user": self.db.get_setting("slack_default_user", ""),
-                },
-                "feishu": {
-                    "configured": self.db.get_setting("feishu_enabled", "false") == "true",
-                    "running": bool(self.feishu_channel and getattr(self.feishu_channel, "_running", False)),
-                },
-            })
+            tg_token = self.db.get_setting("telegram_bot_token", "") or _os.environ.get(
+                "TELEGRAM_BOT_TOKEN", ""
+            )
+            sl_bot = self.db.get_setting("slack_bot_token", "") or _os.environ.get(
+                "SLACK_BOT_TOKEN", ""
+            )
+            sl_app = self.db.get_setting("slack_app_token", "") or _os.environ.get(
+                "SLACK_APP_TOKEN", ""
+            )
+            self._json_response(
+                {
+                    "telegram": {
+                        "enabled": self.db.get_setting("telegram_enabled", "false") == "true",
+                        "configured": bool(tg_token),
+                        "running": bool(
+                            self.telegram_channel
+                            and getattr(self.telegram_channel, "_running", False)
+                        ),
+                        "default_working_dir": self.db.get_setting(
+                            "telegram_default_working_dir", "~"
+                        ),
+                        "default_chat_id": self.db.get_setting("telegram_default_chat_id", ""),
+                        "allowed_users": self.db.get_setting("telegram_allowed_users", ""),
+                    },
+                    "slack": {
+                        "enabled": self.db.get_setting("slack_enabled", "false") == "true",
+                        "configured": bool(sl_bot and sl_app),
+                        "running": bool(
+                            self.slack_channel and getattr(self.slack_channel, "_running", False)
+                        ),
+                        "default_working_dir": self.db.get_setting(
+                            "slack_default_working_dir", "~"
+                        ),
+                        "default_channel": self.db.get_setting("slack_default_channel", ""),
+                        "default_user": self.db.get_setting("slack_default_user", ""),
+                    },
+                    "feishu": {
+                        "configured": self.db.get_setting("feishu_enabled", "false") == "true",
+                        "running": bool(
+                            self.feishu_channel and getattr(self.feishu_channel, "_running", False)
+                        ),
+                    },
+                }
+            )
 
         else:
             self._json_response({"error": "not found"}, 404)
@@ -2435,7 +2785,10 @@ def do_POST(self):
                 expanded = os.path.expanduser(working_dir)
                 if not os.path.isdir(expanded):
                     self._json_response(
-                        {"error": f"working_dir does not exist or is not a directory: {working_dir}", "field": "working_dir"},
+                        {
+                            "error": f"working_dir does not exist or is not a directory: {working_dir}",
+                            "field": "working_dir",
+                        },
                         400,
                     )
                     return
@@ -2444,10 +2797,16 @@ def do_POST(self):
             cron_expr = body.get("cron_expr")
             if schedule_type == "cron":
                 if not cron_expr or not cron_expr.strip():
-                    self._json_response({"error": "cron_expr is required for cron schedule", "field": "cron_expr"}, 400)
+                    self._json_response(
+                        {"error": "cron_expr is required for cron schedule", "field": "cron_expr"},
+                        400,
+                    )
                     return
                 if not croniter.is_valid(cron_expr):
-                    self._json_response({"error": f"invalid cron expression: {cron_expr}", "field": "cron_expr"}, 400)
+                    self._json_response(
+                        {"error": f"invalid cron expression: {cron_expr}", "field": "cron_expr"},
+                        400,
+                    )
                     return
             # ─────────────────────────────────────────────────────────
 
@@ -2476,10 +2835,12 @@ def do_POST(self):
                     if isinstance(item, int):
                         depends_on.append({"task_id": item, "inject_result": False})
                     elif isinstance(item, dict) and "task_id" in item:
-                        depends_on.append({
-                            "task_id": int(item["task_id"]),
-                            "inject_result": bool(item.get("inject_result", False)),
-                        })
+                        depends_on.append(
+                            {
+                                "task_id": int(item["task_id"]),
+                                "inject_result": bool(item.get("inject_result", False)),
+                            }
+                        )
             # Shorthand: global inject_result flag applies to all deps if not per-dep
             if body.get("inject_result") and depends_on:
                 for d in depends_on:
@@ -2510,12 +2871,21 @@ def do_POST(self):
 
         elif path == "/api/feishu/settings":
             logger.info("POST /api/feishu/settings - updating Feishu settings")
-            allowed = {"feishu_app_id", "feishu_app_secret", "feishu_default_chat_id",
-                       "feishu_default_working_dir", "feishu_enabled"}
+            allowed = {
+                "feishu_app_id",
+                "feishu_app_secret",
+                "feishu_default_chat_id",
+                "feishu_default_working_dir",
+                "feishu_enabled",
+            }
             for key, value in body.items():
                 if key in allowed:
                     # Mask sensitive values in logs
-                    display_value = value[:8] + "..." if key in ("feishu_app_id", "feishu_app_secret") else value
+                    display_value = (
+                        value[:8] + "..."
+                        if key in ("feishu_app_id", "feishu_app_secret")
+                        else value
+                    )
                     logger.debug(f"  Setting {key} = {display_value}")
                     self.db.set_setting(key, str(value))
             # Restart the Feishu channel with new credentials
@@ -2526,7 +2896,8 @@ def do_POST(self):
                 self.__class__.feishu_channel = None
             if FEISHU_CHANNEL_AVAILABLE and body.get("feishu_enabled", "").lower() == "true":
                 channel = FeishuChannel(
-                    bus=self.__class__.bus, db=self.db,
+                    bus=self.__class__.bus,
+                    db=self.db,
                     scheduler=self.__class__.scheduler,
                 )
                 logger.info("Starting new Feishu channel (enabled)...")
@@ -2540,32 +2911,50 @@ def do_POST(self):
         elif path == "/api/channels/settings":
             logger.info("POST /api/channels/settings - updating channel settings")
             allowed = {
-                "telegram_bot_token", "telegram_allowed_users",
-                "telegram_default_working_dir", "telegram_enabled", "telegram_default_chat_id",
-                "slack_bot_token", "slack_app_token",
-                "slack_default_working_dir", "slack_default_channel", "slack_default_user", "slack_enabled",
+                "telegram_bot_token",
+                "telegram_allowed_users",
+                "telegram_default_working_dir",
+                "telegram_enabled",
+                "telegram_default_chat_id",
+                "slack_bot_token",
+                "slack_app_token",
+                "slack_default_working_dir",
+                "slack_default_channel",
+                "slack_default_user",
+                "slack_enabled",
             }
             for key, value in body.items():
                 if key in allowed:
                     # Mask sensitive values in logs
-                    display_value = value[:8] + "..." if "token" in key or "secret" in key else value
+                    display_value = (
+                        value[:8] + "..." if "token" in key or "secret" in key else value
+                    )
                     logger.debug(f"  Setting {key} = {display_value}")
                     self.db.set_setting(key, str(value))
 
             # ── Restart Telegram channel ──
-            tg_enabled = (body.get("telegram_enabled") or self.db.get_setting("telegram_enabled", "false")) == "true"
+            tg_enabled = (
+                body.get("telegram_enabled") or self.db.get_setting("telegram_enabled", "false")
+            ) == "true"
             if self.__class__.telegram_channel:
                 logger.info("Stopping existing Telegram channel...")
                 self.__class__.telegram_channel.stop()
                 self.__class__.telegram_channel = None
             if tg_enabled and TELEGRAM_CHANNEL_AVAILABLE:
-                tg_token = self.db.get_setting("telegram_bot_token", "") or os.environ.get("TELEGRAM_BOT_TOKEN", "")
-                tg_allowed = self.db.get_setting("telegram_allowed_users", "") or os.environ.get("TELEGRAM_ALLOWED_USERS", "")
+                tg_token = self.db.get_setting("telegram_bot_token", "") or os.environ.get(
+                    "TELEGRAM_BOT_TOKEN", ""
+                )
+                tg_allowed = self.db.get_setting("telegram_allowed_users", "") or os.environ.get(
+                    "TELEGRAM_ALLOWED_USERS", ""
+                )
                 if tg_token:
                     logger.info("Starting Telegram channel with new settings...")
                     ch = create_telegram_channel(
-                        self.db, self.__class__.scheduler, bus=self.__class__.bus,
-                        token=tg_token, allowed_users_str=tg_allowed,
+                        self.db,
+                        self.__class__.scheduler,
+                        bus=self.__class__.bus,
+                        token=tg_token,
+                        allowed_users_str=tg_allowed,
                     )
                     if ch:
                         ch.start()
@@ -2579,20 +2968,28 @@ def do_POST(self):
                 logger.info("Telegram channel disabled")
 
             # ── Restart Slack channel ──
-            sl_enabled = (body.get("slack_enabled") or self.db.get_setting("slack_enabled", "false")) == "true"
+            sl_enabled = (
+                body.get("slack_enabled") or self.db.get_setting("slack_enabled", "false")
+            ) == "true"
             if self.__class__.slack_channel:
                 logger.info("Stopping existing Slack channel...")
                 self.__class__.slack_channel.stop()
                 self.__class__.slack_channel = None
             if sl_enabled and SLACK_CHANNEL_AVAILABLE:
-                sl_bot = self.db.get_setting("slack_bot_token", "") or os.environ.get("SLACK_BOT_TOKEN", "")
-                sl_app = self.db.get_setting("slack_app_token", "") or os.environ.get("SLACK_APP_TOKEN", "")
+                sl_bot = self.db.get_setting("slack_bot_token", "") or os.environ.get(
+                    "SLACK_BOT_TOKEN", ""
+                )
+                sl_app = self.db.get_setting("slack_app_token", "") or os.environ.get(
+                    "SLACK_APP_TOKEN", ""
+                )
                 if sl_bot and sl_app:
                     logger.info("Starting Slack channel with new settings...")
                     ch = SlackChannel(
-                        bus=self.__class__.bus, db=self.db,
+                        bus=self.__class__.bus,
+                        db=self.db,
                         scheduler=self.__class__.scheduler,
-                        bot_token=sl_bot, app_token=sl_app,
+                        bot_token=sl_bot,
+                        app_token=sl_app,
                     )
                     ch.start()
                     self.__class__.slack_channel = ch
@@ -2623,12 +3020,17 @@ def do_POST(self):
                 depends_on = []
                 for r in depends_on_refs:
                     if r not in ref_to_id:
-                        self._json_response({"error": f"ref '{r}' not found — declare tasks in topological order"}, 400)
+                        self._json_response(
+                            {"error": f"ref '{r}' not found — declare tasks in topological order"},
+                            400,
+                        )
                         return
-                    depends_on.append({
-                        "task_id": ref_to_id[r],
-                        "inject_result": bool(tdef.get("inject_result", False)),
-                    })
+                    depends_on.append(
+                        {
+                            "task_id": ref_to_id[r],
+                            "inject_result": bool(tdef.get("inject_result", False)),
+                        }
+                    )
 
                 prompt_images = tdef.get("prompt_images", [])
                 if isinstance(prompt_images, str):
@@ -2670,13 +3072,19 @@ def do_POST(self):
                 self._json_response({"error": "task not found"}, 404)
                 return
             inject_result = bool(body.get("inject_result", False))
-            should_block = upstream["status"] != "completed" and task["status"] in ("pending", "scheduled")
+            should_block = upstream["status"] != "completed" and task["status"] in (
+                "pending",
+                "scheduled",
+            )
             # Insert dependency and (if needed) update task status atomically.
             with self.db.transaction():
-                self.db.conn.execute("""
+                self.db.conn.execute(
+                    """
                     INSERT OR IGNORE INTO task_dependencies (task_id, depends_on_task_id, inject_result)
                     VALUES (?, ?, ?)
-                """, (tid, int(dep_task_id), 1 if inject_result else 0))
+                """,
+                    (tid, int(dep_task_id), 1 if inject_result else 0),
+                )
                 if should_block:
                     self.db.conn.execute(
                         "UPDATE tasks SET status = ?, updated_at = ? WHERE id = ?",
@@ -2701,12 +3109,9 @@ def do_POST(self):
             answer = body.get("answer", "")
             task = self.db.get_task(tid)
             if task:
-                self.db.update_task(tid,
-                                    status="pending",
-                                    prompt=answer,
-                                    answer=answer,
-                                    question=None,
-                                    error=None)
+                self.db.update_task(
+                    tid, status="pending", prompt=answer, answer=answer, question=None, error=None
+                )
                 self._json_response({"status": "responding"})
             else:
                 self._json_response({"error": "not found"}, 404)
@@ -2722,12 +3127,9 @@ def do_POST(self):
             elif not task.get("session_id"):
                 self._json_response({"error": "no session_id — cannot resume"}, 400)
             else:
-                self.db.update_task(tid,
-                                    status="pending",
-                                    prompt=message,
-                                    result=None,
-                                    error=None,
-                                    question=None)
+                self.db.update_task(
+                    tid, status="pending", prompt=message, result=None, error=None, question=None
+                )
                 self._json_response({"status": "resuming"})
 
         else:
@@ -2792,7 +3194,9 @@ def do_PUT(self):
 
             if task["status"] not in ("pending", "scheduled", "blocked"):
                 self._json_response(
-                    {"error": f"Cannot edit task with status '{task['status']}'. Only pending, scheduled, or blocked tasks can be edited."},
+                    {
+                        "error": f"Cannot edit task with status '{task['status']}'. Only pending, scheduled, or blocked tasks can be edited."
+                    },
                     409,
                 )
                 return
@@ -2809,7 +3213,10 @@ def do_PUT(self):
                 expanded = os.path.expanduser(working_dir)
                 if not os.path.isdir(expanded):
                     self._json_response(
-                        {"error": f"working_dir does not exist: {working_dir}", "field": "working_dir"},
+                        {
+                            "error": f"working_dir does not exist: {working_dir}",
+                            "field": "working_dir",
+                        },
                         400,
                     )
                     return
@@ -2819,17 +3226,29 @@ def do_PUT(self):
             cron_expr = body.get("cron_expr", task.get("cron_expr"))
             if schedule_type == "cron":
                 if not cron_expr or not cron_expr.strip():
-                    self._json_response({"error": "cron_expr required for cron schedule", "field": "cron_expr"}, 400)
+                    self._json_response(
+                        {"error": "cron_expr required for cron schedule", "field": "cron_expr"}, 400
+                    )
                     return
                 if not croniter.is_valid(cron_expr):
-                    self._json_response({"error": f"invalid cron expression: {cron_expr}", "field": "cron_expr"}, 400)
+                    self._json_response(
+                        {"error": f"invalid cron expression: {cron_expr}", "field": "cron_expr"},
+                        400,
+                    )
                     return
 
             # ── Build updates from editable fields ──
             EDITABLE_FIELDS = {
-                "title", "prompt", "working_dir", "schedule_type",
-                "cron_expr", "delay_seconds", "max_runs", "tags",
-                "agent", "dag_id",
+                "title",
+                "prompt",
+                "working_dir",
+                "schedule_type",
+                "cron_expr",
+                "delay_seconds",
+                "max_runs",
+                "tags",
+                "agent",
+                "dag_id",
             }
             updates = {}
             for field in EDITABLE_FIELDS:
@@ -2872,7 +3291,10 @@ def do_PUT(self):
             elif new_stype == "scheduled_at":
                 nra = body.get("next_run_at", task.get("next_run_at"))
                 if not nra:
-                    self._json_response({"error": "next_run_at required for scheduled_at", "field": "next_run_at"}, 400)
+                    self._json_response(
+                        {"error": "next_run_at required for scheduled_at", "field": "next_run_at"},
+                        400,
+                    )
                     return
                 updates["next_run_at"] = nra
                 updates["status"] = "scheduled"
@@ -2895,10 +3317,12 @@ def do_PUT(self):
                         if isinstance(item, int):
                             dep_list.append({"task_id": item, "inject_result": False})
                         elif isinstance(item, dict) and "task_id" in item:
-                            dep_list.append({
-                                "task_id": int(item["task_id"]),
-                                "inject_result": bool(item.get("inject_result", False)),
-                            })
+                            dep_list.append(
+                                {
+                                    "task_id": int(item["task_id"]),
+                                    "inject_result": bool(item.get("inject_result", False)),
+                                }
+                            )
                 if dep_list:
                     self.db.add_dependencies_batch(tid, dep_list)
                     # Check if any deps are unmet → set blocked
@@ -2976,10 +3400,10 @@ def _cors_headers(self):
     @staticmethod
     def _is_allowed_origin(origin: str) -> bool:
         """Return True for file:// (Electron production) and localhost origins."""
-        if origin == "null":           # Electron / file://
+        if origin == "null":  # Electron / file://
             return True
         if not origin:
-            return True                # same-origin request with no Origin header
+            return True  # same-origin request with no Origin header
         # Accept http://localhost or http://localhost:<any port>
         if origin == "http://localhost" or origin.startswith("http://localhost:"):
             return True
@@ -3006,12 +3430,12 @@ def log_message(self, format, *args):
         pass
 
 
-
 class QuietHTTPServer(HTTPServer):
     allow_reuse_address = True
 
     def handle_error(self, request, client_address):
         import sys
+
         if isinstance(sys.exc_info()[1], BrokenPipeError):
             return
         super().handle_error(request, client_address)
@@ -3020,6 +3444,7 @@ def handle_error(self, request, client_address):
 def _kill_stale_process_on_port(port: int):
     """Kill any leftover process occupying the port (e.g. orphaned from a previous run)."""
     import socket
+
     sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
     try:
         sock.settimeout(1)
@@ -3030,8 +3455,7 @@ def _kill_stale_process_on_port(port: int):
     # Port is occupied — try to find and kill the process
     try:
         result = subprocess.run(
-            ["lsof", "-ti", f":{port}"],
-            capture_output=True, text=True, timeout=5
+            ["lsof", "-ti", f":{port}"], capture_output=True, text=True, timeout=5
         )
         pids = []
         for pid_str in result.stdout.strip().split("\n"):
@@ -3095,15 +3519,20 @@ def run_server(port: int = 9712):
     telegram_channel = None
     tg_enabled = db.get_setting("telegram_enabled", "false") == "true"
     tg_token = db.get_setting("telegram_bot_token", "") or os.environ.get("TELEGRAM_BOT_TOKEN", "")
-    tg_allowed = db.get_setting("telegram_allowed_users", "") or os.environ.get("TELEGRAM_ALLOWED_USERS", "")
+    tg_allowed = db.get_setting("telegram_allowed_users", "") or os.environ.get(
+        "TELEGRAM_ALLOWED_USERS", ""
+    )
     # Auto-enable if env var set but settings not yet configured
     if not tg_enabled and os.environ.get("TELEGRAM_BOT_TOKEN"):
         tg_enabled = True
     if TELEGRAM_CHANNEL_AVAILABLE and tg_enabled and tg_token:
         logger.info("Starting Telegram channel...")
         telegram_channel = create_telegram_channel(
-            db, scheduler, bus=bus,
-            token=tg_token, allowed_users_str=tg_allowed,
+            db,
+            scheduler,
+            bus=bus,
+            token=tg_token,
+            allowed_users_str=tg_allowed,
         )
         if telegram_channel:
             telegram_channel.start()
@@ -3122,8 +3551,11 @@ def run_server(port: int = 9712):
     if SLACK_CHANNEL_AVAILABLE and sl_enabled and sl_bot and sl_app:
         logger.info("Starting Slack channel...")
         slack_channel = SlackChannel(
-            bus=bus, db=db, scheduler=scheduler,
-            bot_token=sl_bot, app_token=sl_app,
+            bus=bus,
+            db=db,
+            scheduler=scheduler,
+            bot_token=sl_bot,
+            app_token=sl_app,
         )
         slack_channel.start()
     else:
@@ -3171,7 +3603,9 @@ def shutdown(sig, frame):
 
 if __name__ == "__main__":
     port = int(sys.argv[1]) if len(sys.argv) > 1 else 9712
-    logger.info(f"=== Python backend starting at {datetime.now().strftime('%Y-%m-%d %H:%M:%S')} on port {port} ===")
+    logger.info(
+        f"=== Python backend starting at {datetime.now().strftime('%Y-%m-%d %H:%M:%S')} on port {port} ==="
+    )
     run_server(port)
 # Test comment for hot reload 2026年 2月13日 星期五 23时08分26秒 CST
 # Hot reload test at 23:09:11
diff --git a/taskboard_bus.py b/taskboard_bus.py
index 58398cb..6e16431 100644
--- a/taskboard_bus.py
+++ b/taskboard_bus.py
@@ -48,25 +48,28 @@
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
-from typing import Optional, Callable, TYPE_CHECKING
+from typing import TYPE_CHECKING, Callable, Optional
 
 if TYPE_CHECKING:
-    from taskboard import TaskDB, TaskScheduler
+    from taskboard import TaskDB
 
 
 # ──────────────────────────── Message Types ────────────────────────────
 
+
 class InboundMessageType(str, Enum):
     """Inbound message 的动作类型。"""
-    CREATE_TASK = "create_task"      # 创建新任务
-    RESUME_TASK = "resume_task"      # 恢复已有任务（使用 session_id）
-    RESPOND_TASK = "respond_task"    # 回答任务等待的问题
-    CANCEL_TASK = "cancel_task"      # 取消任务
-    STATUS_QUERY = "status_query"    # 查询任务状态
+
+    CREATE_TASK = "create_task"  # 创建新任务
+    RESUME_TASK = "resume_task"  # 恢复已有任务（使用 session_id）
+    RESPOND_TASK = "respond_task"  # 回答任务等待的问题
+    CANCEL_TASK = "cancel_task"  # 取消任务
+    STATUS_QUERY = "status_query"  # 查询任务状态
 
 
 class OutboundMessageType(str, Enum):
     """Outbound message 的事件类型。"""
+
     TASK_COMPLETED = "task_completed"
     TASK_FAILED = "task_failed"
     TASK_STARTED = "task_started"
@@ -91,6 +94,7 @@ class InboundMessage:
         metadata:    扩展字段，Channel 可存放任意上下文（如 Feishu message_id）。
         created_at:  消息创建时间（UTC ISO 格式）。
     """
+
     type: InboundMessageType
     source: str
     payload: dict = field(default_factory=dict)
@@ -111,6 +115,7 @@ class OutboundMessage:
         metadata:    扩展字段。
         created_at:  消息创建时间（UTC ISO 格式）。
     """
+
     type: OutboundMessageType
     task_id: int
     payload: dict = field(default_factory=dict)
@@ -121,6 +126,7 @@ class OutboundMessage:
 
 # ──────────────────────────── Message Bus ────────────────────────────
 
+
 class MessageBus:
     """AgentForge 的消息总线。
 
@@ -146,7 +152,9 @@ def publish_inbound(self, msg: InboundMessage) -> None:
         """Channel 调用此方法将入站消息放入队列。"""
         self.inbound_queue.put_nowait(msg)
 
-    def get_inbound(self, block: bool = True, timeout: Optional[float] = None) -> Optional[InboundMessage]:
+    def get_inbound(
+        self, block: bool = True, timeout: Optional[float] = None
+    ) -> Optional[InboundMessage]:
         """Scheduler 调用此方法取出下一条入站消息（可选使用）。"""
         try:
             return self.inbound_queue.get(block=block, timeout=timeout)
@@ -177,7 +185,9 @@ def unsubscribe_outbound(self, listener: Callable[[OutboundMessage], None]) -> N
         except ValueError:
             pass
 
-    def get_outbound(self, block: bool = True, timeout: Optional[float] = None) -> Optional[OutboundMessage]:
+    def get_outbound(
+        self, block: bool = True, timeout: Optional[float] = None
+    ) -> Optional[OutboundMessage]:
         """Channel 轮询模式下调用此方法取出出站消息。"""
         try:
             return self.outbound_queue.get(block=block, timeout=timeout)
@@ -187,6 +197,7 @@ def get_outbound(self, block: bool = True, timeout: Optional[float] = None) -> O
 
 # ──────────────────────────── Channel ABC ────────────────────────────
 
+
 class Channel(ABC):
     """消息通道抽象基类。
 
@@ -270,6 +281,7 @@ def _make_inbound(
 
 # ──────────────────────────── UIChannel ────────────────────────────
 
+
 class UIChannel(Channel):
     """HTTP REST API channel（包装现有 TaskAPIHandler + TaskScheduler）。
 
@@ -307,21 +319,30 @@ def get_cached_outbound(self, task_id: int) -> list[OutboundMessage]:
         with self._cache_lock:
             return list(self._outbound_cache.get(task_id, []))
 
-    def notify_task_created(self, task_id: int, prompt: str,
-                             working_dir: str = ".", **kwargs) -> None:
+    def notify_task_created(
+        self, task_id: int, prompt: str, working_dir: str = ".", **kwargs
+    ) -> None:
         """HTTP handler 创建任务后调用，发布 InboundMessage 到 bus。"""
-        self.bus.publish_inbound(self._make_inbound(
-            InboundMessageType.CREATE_TASK,
-            payload={"task_id": task_id, "prompt": prompt,
-                     "working_dir": working_dir, **kwargs},
-        ))
+        self.bus.publish_inbound(
+            self._make_inbound(
+                InboundMessageType.CREATE_TASK,
+                payload={
+                    "task_id": task_id,
+                    "prompt": prompt,
+                    "working_dir": working_dir,
+                    **kwargs,
+                },
+            )
+        )
 
     def notify_task_resumed(self, task_id: int, message: str) -> None:
         """HTTP handler 恢复任务后调用。"""
-        self.bus.publish_inbound(self._make_inbound(
-            InboundMessageType.RESUME_TASK,
-            payload={"task_id": task_id, "message": message},
-        ))
+        self.bus.publish_inbound(
+            self._make_inbound(
+                InboundMessageType.RESUME_TASK,
+                payload={"task_id": task_id, "message": message},
+            )
+        )
 
     def _on_outbound(self, msg: OutboundMessage) -> None:
         """订阅回调：将出站消息写入本地缓存。"""
@@ -330,6 +351,7 @@ def _on_outbound(self, msg: OutboundMessage) -> None:
 
 # ──────────────────────────── BusAwareSchedulerMixin ────────────────────────────
 
+
 class BusAwareSchedulerMixin:
     """可混入 TaskScheduler 的工具方法，让 _notify() 同时发布到 MessageBus。
 
@@ -346,7 +368,9 @@ class BusAwareSchedulerMixin:
 
     bus: Optional[MessageBus] = None
 
-    def _bus_notify(self, task_id: int, override_type: "Optional[OutboundMessageType]" = None) -> None:
+    def _bus_notify(
+        self, task_id: int, override_type: "Optional[OutboundMessageType]" = None
+    ) -> None:
         """根据任务状态向 bus 发布对应的 OutboundMessage。
 
         override_type: 强制使用指定消息类型（用于 cron 任务重调度场景，
diff --git a/tests/conftest.py b/tests/conftest.py
index adcad10..2260c02 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,6 +1,7 @@
 """
 Test configuration for AgentForge.
 """
+
 import sys
 from pathlib import Path
 
diff --git a/tests/test_channel_utils.py b/tests/test_channel_utils.py
new file mode 100644
index 0000000..51bd8e4
--- /dev/null
+++ b/tests/test_channel_utils.py
@@ -0,0 +1,92 @@
+import os
+
+from channels.agent_utils import (
+    SUPPORTED_AGENTS,
+    handle_agent_command,
+    parse_agent_command,
+    resolve_agent,
+)
+from channels.dir_utils import handle_dir_command, parse_dir_command, resolve_working_dir
+from taskboard import _get_env
+
+
+class StubDB:
+    def __init__(self):
+        self.settings = {}
+
+    def set_setting(self, key, value):
+        self.settings[key] = value
+
+    def get_setting(self, key, default=None):
+        return self.settings.get(key, default)
+
+
+def test_parse_dir_command_accepts_supported_forms():
+    assert parse_dir_command("/dir ~/repo") == "~/repo"
+    assert parse_dir_command("/cd ./repo") == "./repo"
+    assert parse_dir_command("cd /tmp/work") == "/tmp/work"
+    assert parse_dir_command("pwd") is None
+
+
+def test_handle_dir_command_persists_setting():
+    db = StubDB()
+
+    result = handle_dir_command("/dir ~/repo", "telegram", db)
+
+    assert result == "📁 Working directory set to: ~/repo"
+    assert db.get_setting("telegram_default_working_dir") == "~/repo"
+
+
+def test_resolve_working_dir_uses_saved_default_when_no_explicit_path(monkeypatch):
+    db = StubDB()
+    db.set_setting("slack_default_working_dir", "~/saved")
+    monkeypatch.setattr("channels.dir_utils.extract_working_dir_with_claude", lambda prompt: None)
+
+    assert resolve_working_dir("please help", "slack", db) == "~/saved"
+
+
+def test_resolve_working_dir_prefers_extracted_path(monkeypatch):
+    db = StubDB()
+    db.set_setting("slack_default_working_dir", "~/saved")
+    monkeypatch.setattr(
+        "channels.dir_utils.extract_working_dir_with_claude",
+        lambda prompt: "~/explicit",
+    )
+
+    assert resolve_working_dir("work in ~/explicit", "slack", db) == "~/explicit"
+
+
+def test_parse_agent_command_normalizes_name():
+    assert parse_agent_command("/agent codex") == "codex"
+    assert parse_agent_command("/agent CLAUDE") == "claude"
+    assert parse_agent_command("/help") is None
+
+
+def test_handle_agent_command_rejects_unknown_agent():
+    db = StubDB()
+
+    result = handle_agent_command("/agent unknown", "telegram", db)
+
+    assert result == "❌ Unknown agent `unknown`. Supported: `claude`, `codex`"
+
+
+def test_handle_agent_command_persists_default_agent():
+    db = StubDB()
+
+    result = handle_agent_command("/agent codex", "telegram", db)
+
+    assert result == f"🤖 Default agent switched to: **{SUPPORTED_AGENTS['codex']}**"
+    assert db.get_setting("default_agent") == "codex"
+    assert resolve_agent("telegram", db) == "codex"
+
+
+def test_get_env_prepends_common_tool_paths(monkeypatch):
+    monkeypatch.setenv("PATH", "/usr/bin:/bin")
+    monkeypatch.setattr(os.path, "expanduser", lambda path: path.replace("~", "/Users/tester"))
+
+    env = _get_env()
+
+    assert env["PATH"].startswith(
+        "/Users/tester/.local/bin:/usr/local/bin:/opt/homebrew/bin:/usr/local/opt/node/bin:"
+        "/Users/tester/.npm/bin:/Users/tester/.nvm/current/bin:/usr/bin:/bin"
+    )
diff --git a/tests/test_feishu_forwarded_messages.py b/tests/test_feishu_forwarded_messages.py
index 15c4cbb..9f51a25 100644
--- a/tests/test_feishu_forwarded_messages.py
+++ b/tests/test_feishu_forwarded_messages.py
@@ -3,15 +3,15 @@
 """
 
 import json
+from unittest.mock import Mock, patch
+
 import pytest
-from unittest.mock import Mock, MagicMock, patch
-from datetime import datetime
 
 
 @pytest.fixture
 def mock_feishu_channel():
     """Create a mock FeishuChannel instance for testing."""
-    with patch('channels.feishu_channel.FEISHU_AVAILABLE', True):
+    with patch("channels.feishu_channel.FEISHU_AVAILABLE", True):
         from channels.feishu_channel import FeishuChannel
 
         bus = Mock()
@@ -33,13 +33,15 @@ def test_extract_forwarded_content_forward_type(self, mock_feishu_channel):
         """Test extraction of 'forward' type messages."""
         message = Mock()
         message.message_type = "forward"
-        message.content = json.dumps({
-            "sender_name": "张三",
-            "sender_id": "ou_123456789",
-            "create_time": 1738080000,
-            "text": "这是一条转发的消息",
-            "images": []
-        })
+        message.content = json.dumps(
+            {
+                "sender_name": "张三",
+                "sender_id": "ou_123456789",
+                "create_time": 1738080000,
+                "text": "这是一条转发的消息",
+                "images": [],
+            }
+        )
 
         result = mock_feishu_channel._extract_forwarded_content(message)
 
@@ -54,21 +56,22 @@ def test_extract_forwarded_content_quote_type(self, mock_feishu_channel):
         """Test extraction of quote type messages."""
         message = Mock()
         message.message_type = "post"
-        message.content = json.dumps({
-            "zh_cn": {
-                "content": [[
-                    {
-                        "tag": "quote",
-                        "text": "被引用的文本内容",
-                        "user": {
-                            "name": "李四",
-                            "open_id": "ou_987654321"
-                        },
-                        "create_time": 1738083600
-                    }
-                ]]
+        message.content = json.dumps(
+            {
+                "zh_cn": {
+                    "content": [
+                        [
+                            {
+                                "tag": "quote",
+                                "text": "被引用的文本内容",
+                                "user": {"name": "李四", "open_id": "ou_987654321"},
+                                "create_time": 1738083600,
+                            }
+                        ]
+                    ]
+                }
             }
-        })
+        )
 
         result = mock_feishu_channel._extract_forwarded_content(message)
 
@@ -83,22 +86,24 @@ def test_extract_forwarded_content_nested_message(self, mock_feishu_channel):
         """Test extraction of nested_message type (forward) in post."""
         message = Mock()
         message.message_type = "post"
-        message.content = json.dumps({
-            "content": [[
-                {
-                    "tag": "nested_message",
-                    "nested_message": {
-                        "sender_name": "王五",
-                        "sender_id": "ou_555555555",
-                        "create_time": 1738087200,
-                        "text": "嵌套消息内容",
-                        "images": [
-                            {"image_key": "img_v2_abcd1234"}
-                        ]
-                    }
-                }
-            ]]
-        })
+        message.content = json.dumps(
+            {
+                "content": [
+                    [
+                        {
+                            "tag": "nested_message",
+                            "nested_message": {
+                                "sender_name": "王五",
+                                "sender_id": "ou_555555555",
+                                "create_time": 1738087200,
+                                "text": "嵌套消息内容",
+                                "images": [{"image_key": "img_v2_abcd1234"}],
+                            },
+                        }
+                    ]
+                ]
+            }
+        )
 
         result = mock_feishu_channel._extract_forwarded_content(message)
 
@@ -141,7 +146,7 @@ def test_format_forwarded_prompt_basic(self, mock_feishu_channel):
             "sender_id": "ou_123456",
             "timestamp": 1738080000,
             "text": "这是转发的内容",
-            "images": []
+            "images": [],
         }
         original_content = "请帮我分析上述消息"
 
@@ -161,7 +166,7 @@ def test_format_forwarded_prompt_no_timestamp(self, mock_feishu_channel):
             "type": "forward",
             "sender_name": "李四",
             "text": "无时间戳的转发",
-            "images": []
+            "images": [],
         }
         original_content = "看看这个"
 
@@ -176,10 +181,7 @@ def test_format_forwarded_prompt_with_images(self, mock_feishu_channel):
             "type": "forward",
             "sender_name": "王五",
             "text": "一张图片",
-            "images": [
-                {"image_key": "img1"},
-                {"image_key": "img2"}
-            ]
+            "images": [{"image_key": "img1"}, {"image_key": "img2"}],
         }
         original_content = ""
 
@@ -193,7 +195,7 @@ def test_format_forwarded_prompt_no附加消息(self, mock_feishu_channel):
             "type": "quote",
             "sender_name": "赵六",
             "text": "只是引用没有附加消息",
-            "images": []
+            "images": [],
         }
         original_content = "   "  # Only spaces
 
@@ -223,19 +225,14 @@ def test_format_forwarded_prompt_empty_forwarded(self, mock_feishu_channel):
 class TestForwardedImageHandling:
     """Test handling of images in forwarded messages."""
 
-    def test_download_image_called_for_forwarded_images(
-        self, mock_feishu_channel
-    ):
+    def test_download_image_called_for_forwarded_images(self, mock_feishu_channel):
         """Test that images in forwarded messages are downloaded."""
         # Simulate forwarded message with images
         forwarded = {
             "type": "forward",
             "sender_name": "测试用户",
             "text": "带图片的转发",
-            "images": [
-                {"image_key": "img_key_1"},
-                {"image_key": "img_key_2"}
-            ]
+            "images": [{"image_key": "img_key_1"}, {"image_key": "img_key_2"}],
         }
 
         message = Mock()
@@ -270,7 +267,7 @@ def test_telegram_forwarded_from_user(self, mock_feishu_channel):
             "sender_id": "telegram_user_12345",
             "timestamp": 1738080000,
             "text": "Hey, did you see the new feature?",
-            "images": []
+            "images": [],
         }
         original_content = "Can you explain this feature?"
 
@@ -286,10 +283,8 @@ def test_channel_forwarded_post(self, mock_feishu_channel):
             "type": "forward",
             "sender_name": "技术资讯频道",
             "text": "发布了一个新的AI模型，效果惊人...\n\nLink: https://example.com",
-            "images": [
-                {"image_key": "chart_123"}
-            ],
-            "timestamp": 1738087200
+            "images": [{"image_key": "chart_123"}],
+            "timestamp": 1738087200,
         }
         original_content = "帮我总结一下这个新闻"
 
@@ -307,7 +302,7 @@ def test_nested_forward_chain(self, mock_feishu_channel):
             "sender_name": "传播者B",
             "text": "传播者A: 原始发布者: 这是最初的消息",
             "timestamp": 1738090800,
-            "images": []
+            "images": [],
         }
         original_content = ""
 
diff --git a/tests/test_heartbeat.py b/tests/test_heartbeat.py
index 77710d9..cce0e4a 100644
--- a/tests/test_heartbeat.py
+++ b/tests/test_heartbeat.py
@@ -2,8 +2,8 @@
 
 from taskboard import (
     Heartbeat,
-    HeartbeatScheduleType,
     HeartbeatDecisionType,
+    HeartbeatScheduleType,
     ScheduleType,
     TaskDB,
     TaskScheduler,
@@ -56,11 +56,13 @@ def test_heartbeat_trigger_creates_task_and_tick(tmp_path, monkeypatch):
         "prompt": "Review commit abc123.",
         "metadata": {},
     }
+
     def fake_run(agent, cmd, cwd, on_stdout_line=None, on_stderr_line=None):
         payload = json.dumps(decision)
         if on_stdout_line:
             on_stdout_line(payload)
         return True, payload
+
     monkeypatch.setattr(scheduler, "_run_agent_command", fake_run)
 
     scheduler._execute_heartbeat(heartbeat)
@@ -97,11 +99,13 @@ def test_heartbeat_duplicate_signal_is_suppressed(tmp_path, monkeypatch):
         "prompt": "Review commit abc123.",
         "metadata": {},
     }
+
     def fake_run(agent, cmd, cwd, on_stdout_line=None, on_stderr_line=None):
         payload = json.dumps(decision)
         if on_stdout_line:
             on_stdout_line(payload)
         return True, payload
+
     monkeypatch.setattr(scheduler, "_run_agent_command", fake_run)
 
     scheduler._execute_heartbeat(heartbeat)
@@ -129,6 +133,7 @@ def fake_run(agent, cmd, cwd, on_stdout_line=None, on_stderr_line=None):
         if on_stdout_line:
             on_stdout_line("not json")
         return True, "not json"
+
     monkeypatch.setattr(scheduler, "_run_agent_command", fake_run)
 
     scheduler._execute_heartbeat(heartbeat)
diff --git a/tests/test_taskboard_bus.py b/tests/test_taskboard_bus.py
new file mode 100644
index 0000000..da49af3
--- /dev/null
+++ b/tests/test_taskboard_bus.py
@@ -0,0 +1,230 @@
+from taskboard_bus import (
+    BusAwareSchedulerMixin,
+    Channel,
+    InboundMessageType,
+    MessageBus,
+    OutboundMessage,
+    OutboundMessageType,
+    UIChannel,
+)
+
+
+class StubDB:
+    def __init__(self, tasks=None):
+        self.tasks = tasks or {}
+
+    def get_task(self, task_id):
+        return self.tasks.get(task_id)
+
+
+class RecordingChannel(Channel):
+    def __init__(self, bus, db):
+        super().__init__("test", bus, db)
+        self.sent = []
+
+    def send(self, msg):
+        self.sent.append(msg)
+
+    def start(self):
+        self._running = True
+
+
+class FakeScheduler(BusAwareSchedulerMixin):
+    def __init__(self, db, bus=None):
+        self.db = db
+        self.bus = bus
+
+
+def test_message_bus_round_trips_inbound_and_outbound_messages():
+    bus = MessageBus()
+    inbound = RecordingChannel(bus, StubDB())._make_inbound(
+        InboundMessageType.CREATE_TASK,
+        {"title": "hello"},
+        reply_to="chat-1",
+        metadata={"source_message_id": "m1"},
+    )
+    outbound = OutboundMessage(
+        type=OutboundMessageType.TASK_COMPLETED,
+        task_id=1,
+        payload={"status": "completed"},
+    )
+
+    bus.publish_inbound(inbound)
+    bus.publish_outbound(outbound)
+
+    assert bus.get_inbound() == inbound
+    assert bus.get_outbound() == outbound
+
+
+def test_message_bus_returns_none_when_queue_is_empty():
+    bus = MessageBus()
+
+    assert bus.get_inbound(block=False) is None
+    assert bus.get_outbound(block=False) is None
+
+
+def test_message_bus_notifies_and_unsubscribes_outbound_listeners():
+    bus = MessageBus()
+    seen = []
+
+    def listener(msg):
+        seen.append(msg.task_id)
+
+    bus.subscribe_outbound(listener)
+    bus.publish_outbound(
+        OutboundMessage(
+            type=OutboundMessageType.TASK_STARTED,
+            task_id=7,
+        )
+    )
+    bus.unsubscribe_outbound(listener)
+    bus.publish_outbound(
+        OutboundMessage(
+            type=OutboundMessageType.TASK_COMPLETED,
+            task_id=8,
+        )
+    )
+
+    assert seen == [7]
+
+
+def test_message_bus_tolerates_listener_errors_and_missing_unsubscribe():
+    bus = MessageBus()
+
+    def bad_listener(msg):
+        raise RuntimeError("boom")
+
+    bus.subscribe_outbound(bad_listener)
+    bus.publish_outbound(
+        OutboundMessage(
+            type=OutboundMessageType.TASK_UPDATED,
+            task_id=9,
+        )
+    )
+    bus.unsubscribe_outbound(bad_listener)
+    bus.unsubscribe_outbound(bad_listener)
+
+    assert bus.get_outbound().task_id == 9
+
+
+def test_channel_notify_task_maps_task_status_to_outbound_type():
+    bus = MessageBus()
+    db = StubDB(
+        {
+            1: {"status": "completed", "result": "ok", "error": None, "title": "done"},
+            2: {"status": "failed", "result": None, "error": "boom", "title": "bad"},
+        }
+    )
+    channel = RecordingChannel(bus, db)
+
+    channel.notify_task(1)
+    channel.notify_task(2)
+    channel.notify_task(999)
+
+    assert [msg.type for msg in channel.sent] == [
+        OutboundMessageType.TASK_COMPLETED,
+        OutboundMessageType.TASK_FAILED,
+    ]
+    assert channel.sent[0].payload["result"] == "ok"
+    assert channel.sent[1].payload["error"] == "boom"
+
+
+def test_channel_stop_marks_channel_as_not_running():
+    channel = RecordingChannel(MessageBus(), StubDB())
+    channel.start()
+
+    channel.stop()
+
+    assert channel._running is False
+
+
+def test_ui_channel_caches_outbound_messages_and_inbound_notifications():
+    bus = MessageBus()
+    db = StubDB()
+    channel = UIChannel(bus, db)
+
+    channel.start()
+    created = channel._make_inbound(
+        InboundMessageType.CREATE_TASK,
+        {"task_id": 1, "prompt": "hello"},
+    )
+    bus.publish_inbound(created)
+    channel.notify_task_created(1, "hello", "~/repo", tags="ops")
+    channel.notify_task_resumed(1, "continue")
+    bus.publish_outbound(
+        OutboundMessage(
+            type=OutboundMessageType.TASK_UPDATED,
+            task_id=1,
+            payload={"status": "running"},
+        )
+    )
+
+    inbound_messages = [bus.get_inbound(), bus.get_inbound(), bus.get_inbound()]
+    cached = channel.get_cached_outbound(1)
+
+    assert channel._running is True
+    assert [msg.type for msg in inbound_messages] == [
+        InboundMessageType.CREATE_TASK,
+        InboundMessageType.CREATE_TASK,
+        InboundMessageType.RESUME_TASK,
+    ]
+    assert inbound_messages[1].payload["working_dir"] == "~/repo"
+    assert inbound_messages[1].payload["tags"] == "ops"
+    assert inbound_messages[2].payload["message"] == "continue"
+    assert len(cached) == 1
+    assert cached[0].payload["status"] == "running"
+
+
+def test_ui_channel_evicts_oldest_task_cache_entries():
+    bus = MessageBus()
+    channel = UIChannel(bus, StubDB())
+    channel._CACHE_MAX_TASKS = 2
+
+    for task_id in (1, 2, 3):
+        channel.send(
+            OutboundMessage(
+                type=OutboundMessageType.TASK_UPDATED,
+                task_id=task_id,
+            )
+        )
+
+    assert sorted(channel._outbound_cache) == [2, 3]
+
+
+def test_bus_aware_scheduler_mixin_publishes_task_updates():
+    bus = MessageBus()
+    db = StubDB(
+        {
+            1: {"status": "completed", "result": "ok", "error": None, "title": "done"},
+            2: {"status": "running", "result": None, "error": None, "title": "work"},
+        }
+    )
+    scheduler = FakeScheduler(db, bus)
+
+    scheduler._bus_notify(1)
+    scheduler._bus_notify(2, override_type=OutboundMessageType.STATUS_RESPONSE)
+    scheduler._bus_notify(999)
+
+    first = bus.get_outbound()
+    second = bus.get_outbound()
+
+    assert first.type == OutboundMessageType.TASK_COMPLETED
+    assert first.payload["title"] == "done"
+    assert second.type == OutboundMessageType.STATUS_RESPONSE
+    assert second.payload["status"] == "running"
+
+
+def test_bus_aware_scheduler_mixin_noops_without_bus():
+    scheduler = FakeScheduler(StubDB({1: {"status": "completed"}}), bus=None)
+
+    scheduler._bus_notify(1)
+
+
+def test_bus_aware_scheduler_mixin_tolerates_db_errors():
+    class BrokenDB:
+        def get_task(self, task_id):
+            raise RuntimeError("db down")
+
+    scheduler = FakeScheduler(BrokenDB(), MessageBus())
+
+    scheduler._bus_notify(1)
diff --git a/tests/test_telegram_forwarded_messages.py b/tests/test_telegram_forwarded_messages.py
index 0b7fecd..574a6ac 100644
--- a/tests/test_telegram_forwarded_messages.py
+++ b/tests/test_telegram_forwarded_messages.py
@@ -2,17 +2,16 @@
 Tests for Telegram forwarded message handling functionality.
 """
 
-import json
-import pytest
-from unittest.mock import Mock, MagicMock, AsyncMock, patch
-from datetime import datetime
 from dataclasses import dataclass
+from unittest.mock import Mock, patch
+
+import pytest
 
 
 @pytest.fixture
 def mock_telegram_channel():
     """Create a mock TelegramChannel instance for testing."""
-    with patch('channels.telegram_channel.TELEGRAM_AVAILABLE', True):
+    with patch("channels.telegram_channel.TELEGRAM_AVAILABLE", True):
         from channels.telegram_channel import TelegramChannel
 
         bus = Mock()
@@ -20,11 +19,7 @@ def mock_telegram_channel():
         scheduler = Mock()
 
         channel = TelegramChannel(
-            bus=bus,
-            db=db,
-            scheduler=scheduler,
-            token="fake_token",
-            allowed_users=None
+            bus=bus, db=db, scheduler=scheduler, token="fake_token", allowed_users=None
         )
 
         # Mock the app and loop
@@ -39,6 +34,7 @@ def mock_telegram_channel():
 @dataclass
 class MockUser:
     """Mock Telegram User object."""
+
     id: int
     first_name: str
     last_name: str = ""
@@ -52,6 +48,7 @@ def __getattr__(self, name):
 @dataclass
 class MockChat:
     """Mock Telegram Chat object."""
+
     id: int
     type: str = "private"
     title: str = ""
@@ -64,6 +61,7 @@ def __getattr__(self, name):
 @dataclass
 class MockMessage:
     """Mock Telegram Message object."""
+
     message_id: int
     text: str
     from_user: MockUser
@@ -83,10 +81,7 @@ class TestTelegramForwardMessageDetection:
     def test_format_forwarded_text_from_user(self, mock_telegram_channel):
         """Test formatting a message forwarded from a user."""
         forward_user = MockUser(
-            id=12345,
-            first_name="Alice",
-            last_name="Smith",
-            username="alice_smith"
+            id=12345, first_name="Alice", last_name="Smith", username="alice_smith"
         )
 
         message = MockMessage(
@@ -95,7 +90,7 @@ def test_format_forwarded_text_from_user(self, mock_telegram_channel):
             from_user=MockUser(id=999, first_name="Bob"),
             chat=MockChat(id=888, type="private"),
             forward_from=forward_user,
-            forward_date=1738080000
+            forward_date=1738080000,
         )
 
         update = Mock()
@@ -111,12 +106,7 @@ def test_format_forwarded_text_from_user(self, mock_telegram_channel):
 
     def test_format_forwarded_text_from_user_no_username(self, mock_telegram_channel):
         """Test formatting when forwarded user has no username."""
-        forward_user = MockUser(
-            id=12345,
-            first_name="张三",
-            last_name="李四",
-            username=""
-        )
+        forward_user = MockUser(id=12345, first_name="张三", last_name="李四", username="")
 
         message = MockMessage(
             message_id=100,
@@ -124,7 +114,7 @@ def test_format_forwarded_text_from_user_no_username(self, mock_telegram_channel
             from_user=MockUser(id=999, first_name="王五"),
             chat=MockChat(id=888, type="private"),
             forward_from=forward_user,
-            forward_date=1738080000
+            forward_date=1738080000,
         )
 
         update = Mock()
@@ -136,12 +126,7 @@ def test_format_forwarded_text_from_user_no_username(self, mock_telegram_channel
 
     def test_format_forwarded_text_from_user_only_firstname(self, mock_telegram_channel):
         """Test formatting when forwarded user has only first name."""
-        forward_user = MockUser(
-            id=12345,
-            first_name="Charlie",
-            last_name="",
-            username=""
-        )
+        forward_user = MockUser(id=12345, first_name="Charlie", last_name="", username="")
 
         message = MockMessage(
             message_id=100,
@@ -149,7 +134,7 @@ def test_format_forwarded_text_from_user_only_firstname(self, mock_telegram_chan
             from_user=MockUser(id=999, first_name="Dave"),
             chat=MockChat(id=888, type="private"),
             forward_from=forward_user,
-            forward_date=1738080000
+            forward_date=1738080000,
         )
 
         update = Mock()
@@ -162,10 +147,7 @@ def test_format_forwarded_text_from_user_only_firstname(self, mock_telegram_chan
     def test_format_forwarded_text_from_channel(self, mock_telegram_channel):
         """Test formatting a message forwarded from a channel."""
         forward_chat = MockChat(
-            id=-100123456789,
-            type="channel",
-            title="Tech News",
-            username="technews"
+            id=-100123456789, type="channel", title="Tech News", username="technews"
         )
 
         message = MockMessage(
@@ -174,7 +156,7 @@ def test_format_forwarded_text_from_channel(self, mock_telegram_channel):
             from_user=MockUser(id=999, first_name="Reader"),
             chat=MockChat(id=888, type="private"),
             forward_from_chat=forward_chat,
-            forward_date=1738083600
+            forward_date=1738083600,
         )
 
         update = Mock()
@@ -188,10 +170,7 @@ def test_format_forwarded_text_from_channel(self, mock_telegram_channel):
     def test_format_forwarded_text_from_group(self, mock_telegram_channel):
         """Test formatting a message forwarded from a group."""
         forward_chat = MockChat(
-            id=-100987654321,
-            type="supergroup",
-            title="Python Developers",
-            username=""
+            id=-100987654321, type="supergroup", title="Python Developers", username=""
         )
 
         message = MockMessage(
@@ -200,7 +179,7 @@ def test_format_forwarded_text_from_group(self, mock_telegram_channel):
             from_user=MockUser(id=999, first_name="Dev"),
             chat=MockChat(id=888, type="private"),
             forward_from_chat=forward_chat,
-            forward_date=1738087200
+            forward_date=1738087200,
         )
 
         update = Mock()
@@ -212,12 +191,7 @@ def test_format_forwarded_text_from_group(self, mock_telegram_channel):
 
     def test_format_forwarded_text_from_chat_no_title(self, mock_telegram_channel):
         """Test formatting when forwarded chat has no title."""
-        forward_chat = MockChat(
-            id=-100111222333,
-            type="group",
-            title="",
-            username="unknown_group"
-        )
+        forward_chat = MockChat(id=-100111222333, type="group", title="", username="unknown_group")
 
         message = MockMessage(
             message_id=100,
@@ -225,7 +199,7 @@ def test_format_forwarded_text_from_chat_no_title(self, mock_telegram_channel):
             from_user=MockUser(id=999, first_name="User"),
             chat=MockChat(id=888, type="private"),
             forward_from_chat=forward_chat,
-            forward_date=1738080000
+            forward_date=1738080000,
         )
 
         update = Mock()
@@ -245,7 +219,7 @@ def test_format_forwarded_text_no_timestamp(self, mock_telegram_channel):
             from_user=MockUser(id=999, first_name="User"),
             chat=MockChat(id=888, type="private"),
             forward_from=forward_user,
-            forward_date=None
+            forward_date=None,
         )
 
         update = Mock()
@@ -264,7 +238,7 @@ def test_format_forwarded_text_not_forwarded(self, mock_telegram_channel):
             message_id=100,
             text="Regular message",
             from_user=MockUser(id=999, first_name="User"),
-            chat=MockChat(id=888, type="private")
+            chat=MockChat(id=888, type="private"),
         )
 
         update = Mock()
@@ -284,7 +258,7 @@ def test_format_forwarded_text_fallback_to_generic_sender(self, mock_telegram_ch
             chat=MockChat(id=888, type="private"),
             forward_from=None,
             forward_from_chat=None,
-            forward_date=1738080000
+            forward_date=1738080000,
         )
 
         update = Mock()
@@ -304,8 +278,8 @@ def test_format_forwarded_text_fallback_to_generic_sender(self, mock_telegram_ch
 class TestTelegramForwardedTaskCreation:
     """Test task creation from forwarded messages."""
 
-    @patch('taskboard.Task')
-    @patch('taskboard.ScheduleType')
+    @patch("taskboard.Task")
+    @patch("taskboard.ScheduleType")
     def test_create_task_from_forwarded_message(
         self, mock_schedule_type, mock_task_class, mock_telegram_channel
     ):
@@ -318,7 +292,7 @@ def test_create_task_from_forwarded_message(
             from_user=MockUser(id=999, first_name="Bob"),
             chat=MockChat(id=888, type="private"),
             forward_from=forward_user,
-            forward_date=1738080000
+            forward_date=1738080000,
         )
 
         update = Mock()
@@ -342,8 +316,8 @@ def test_create_task_from_forwarded_message(
         assert ", forwarded" in call_kwargs["tags"]
         assert "📨 " in call_kwargs["title"]
 
-    @patch('taskboard.Task')
-    @patch('taskboard.ScheduleType')
+    @patch("taskboard.Task")
+    @patch("taskboard.ScheduleType")
     def test_create_task_from_normal_message(
         self, mock_schedule_type, mock_task_class, mock_telegram_channel
     ):
@@ -352,7 +326,7 @@ def test_create_task_from_normal_message(
             message_id=100,
             text="Regular task",
             from_user=MockUser(id=999, first_name="Bob"),
-            chat=MockChat(id=888, type="private")
+            chat=MockChat(id=888, type="private"),
         )
 
         update = Mock()
@@ -379,11 +353,7 @@ class TestTelegramForwardedMessageScenarios:
 
     def test_user_forwards_news_article(self, mock_telegram_channel):
         """Simulate a user forwarding a news article from a channel."""
-        forward_chat = MockChat(
-            id=-100123456789,
-            type="channel",
-            title="Breaking News"
-        )
+        forward_chat = MockChat(id=-100123456789, type="channel", title="Breaking News")
 
         message = MockMessage(
             message_id=100,
@@ -391,7 +361,7 @@ def test_user_forwards_news_article(self, mock_telegram_channel):
             from_user=MockUser(id=999, first_name="Investor"),
             chat=MockChat(id=888, type="private"),
             forward_from_chat=forward_chat,
-            forward_date=1738080000
+            forward_date=1738080000,
         )
 
         update = Mock()
@@ -412,7 +382,7 @@ def test_user_forwards_another_users_code(self, mock_telegram_channel):
             from_user=MockUser(id=999, first_name="Learner"),
             chat=MockChat(id=888, type="private"),
             forward_from=forward_user,
-            forward_date=1738083600
+            forward_date=1738083600,
         )
 
         update = Mock()
@@ -440,7 +410,7 @@ def test_forwarded_multiline_message(self, mock_telegram_channel):
             from_user=MockUser(id=999, first_name="Receiver"),
             chat=MockChat(id=888, type="private"),
             forward_from=forward_user,
-            forward_date=1738087200
+            forward_date=1738087200,
         )
 
         update = Mock()
@@ -463,7 +433,7 @@ def test_empty_text_with_forward(self, mock_telegram_channel):
             from_user=MockUser(id=999, first_name="User"),
             chat=MockChat(id=888, type="private"),
             forward_from=forward_user,
-            forward_date=1738080000
+            forward_date=1738080000,
         )
 
         update = Mock()
@@ -479,8 +449,8 @@ def test_empty_text_with_forward(self, mock_telegram_channel):
 class TestTelegramForwardedMessageIntegration:
     """Integration tests for the complete forwarded message flow."""
 
-    @patch('taskboard.Task')
-    @patch('taskboard.ScheduleType')
+    @patch("taskboard.Task")
+    @patch("taskboard.ScheduleType")
     def test_complete_forwarded_message_flow(
         self, mock_schedule_type, mock_task_class, mock_telegram_channel
     ):
@@ -496,7 +466,7 @@ def test_complete_forwarded_message_flow(
             from_user=current_user,
             chat=chat,
             forward_from=forward_user,
-            forward_date=1738080000
+            forward_date=1738080000,
         )
 
         update = Mock()
diff --git a/uv.lock b/uv.lock
index d5206b9..4d8fbef 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1,5 +1,5 @@
 version = 1
-revision = 3
+revision = 2
 requires-python = ">=3.12"
 resolution-markers = [
     "python_full_version >= '3.14'",
@@ -27,6 +27,8 @@ dependencies = [
 dev = [
     { name = "pyinstaller" },
     { name = "pytest" },
+    { name = "pytest-cov" },
+    { name = "ruff" },
 ]
 
 [package.metadata]
@@ -47,6 +49,8 @@ requires-dist = [
 dev = [
     { name = "pyinstaller", specifier = ">=6.18.0" },
     { name = "pytest", specifier = ">=9.0.2" },
+    { name = "pytest-cov", specifier = ">=7.0.0" },
+    { name = "ruff", specifier = ">=0.11.0" },
 ]
 
 [[package]]
@@ -173,6 +177,90 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
 ]
 
+[[package]]
+name = "coverage"
+version = "7.13.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9d/e0/70553e3000e345daff267cec284ce4cbf3fc141b6da229ac52775b5428f1/coverage-7.13.5.tar.gz", hash = "sha256:c81f6515c4c40141f83f502b07bbfa5c240ba25bbe73da7b33f1e5b6120ff179", size = 915967, upload-time = "2026-03-17T10:33:18.341Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a0/c3/a396306ba7db865bf96fc1fb3b7fd29bcbf3d829df642e77b13555163cd6/coverage-7.13.5-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:460cf0114c5016fa841214ff5564aa4864f11948da9440bc97e21ad1f4ba1e01", size = 219554, upload-time = "2026-03-17T10:30:42.208Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/16/a68a19e5384e93f811dccc51034b1fd0b865841c390e3c931dcc4699e035/coverage-7.13.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:0e223ce4b4ed47f065bfb123687686512e37629be25cc63728557ae7db261422", size = 219908, upload-time = "2026-03-17T10:30:43.906Z" },
+    { url = "https://files.pythonhosted.org/packages/29/72/20b917c6793af3a5ceb7fb9c50033f3ec7865f2911a1416b34a7cfa0813b/coverage-7.13.5-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:6e3370441f4513c6252bf042b9c36d22491142385049243253c7e48398a15a9f", size = 251419, upload-time = "2026-03-17T10:30:45.545Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/49/cd14b789536ac6a4778c453c6a2338bc0a2fb60c5a5a41b4008328b9acc1/coverage-7.13.5-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:03ccc709a17a1de074fb1d11f217342fb0d2b1582ed544f554fc9fc3f07e95f5", size = 254159, upload-time = "2026-03-17T10:30:47.204Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/00/7b0edcfe64e2ed4c0340dac14a52ad0f4c9bd0b8b5e531af7d55b703db7c/coverage-7.13.5-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3f4818d065964db3c1c66dc0fbdac5ac692ecbc875555e13374fdbe7eedb4376", size = 255270, upload-time = "2026-03-17T10:30:48.812Z" },
+    { url = "https://files.pythonhosted.org/packages/93/89/7ffc4ba0f5d0a55c1e84ea7cee39c9fc06af7b170513d83fbf3bbefce280/coverage-7.13.5-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:012d5319e66e9d5a218834642d6c35d265515a62f01157a45bcc036ecf947256", size = 257538, upload-time = "2026-03-17T10:30:50.77Z" },
+    { url = "https://files.pythonhosted.org/packages/81/bd/73ddf85f93f7e6fa83e77ccecb6162d9415c79007b4bc124008a4995e4a7/coverage-7.13.5-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:8dd02af98971bdb956363e4827d34425cb3df19ee550ef92855b0acb9c7ce51c", size = 251821, upload-time = "2026-03-17T10:30:52.5Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/81/278aff4e8dec4926a0bcb9486320752811f543a3ce5b602cc7a29978d073/coverage-7.13.5-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:f08fd75c50a760c7eb068ae823777268daaf16a80b918fa58eea888f8e3919f5", size = 253191, upload-time = "2026-03-17T10:30:54.543Z" },
+    { url = "https://files.pythonhosted.org/packages/70/ee/fe1621488e2e0a58d7e94c4800f0d96f79671553488d401a612bebae324b/coverage-7.13.5-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:843ea8643cf967d1ac7e8ecd4bb00c99135adf4816c0c0593fdcc47b597fcf09", size = 251337, upload-time = "2026-03-17T10:30:56.663Z" },
+    { url = "https://files.pythonhosted.org/packages/37/a6/f79fb37aa104b562207cc23cb5711ab6793608e246cae1e93f26b2236ed9/coverage-7.13.5-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:9d44d7aa963820b1b971dbecd90bfe5fe8f81cff79787eb6cca15750bd2f79b9", size = 255404, upload-time = "2026-03-17T10:30:58.427Z" },
+    { url = "https://files.pythonhosted.org/packages/75/f0/ed15262a58ec81ce457ceb717b7f78752a1713556b19081b76e90896e8d4/coverage-7.13.5-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:7132bed4bd7b836200c591410ae7d97bf7ae8be6fc87d160b2bd881df929e7bf", size = 250903, upload-time = "2026-03-17T10:31:00.093Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/e9/9129958f20e7e9d4d56d51d42ccf708d15cac355ff4ac6e736e97a9393d2/coverage-7.13.5-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:a698e363641b98843c517817db75373c83254781426e94ada3197cabbc2c919c", size = 252780, upload-time = "2026-03-17T10:31:01.916Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/d7/0ad9b15812d81272db94379fe4c6df8fd17781cc7671fdfa30c76ba5ff7b/coverage-7.13.5-cp312-cp312-win32.whl", hash = "sha256:bdba0a6b8812e8c7df002d908a9a2ea3c36e92611b5708633c50869e6d922fdf", size = 222093, upload-time = "2026-03-17T10:31:03.642Z" },
+    { url = "https://files.pythonhosted.org/packages/29/3d/821a9a5799fac2556bcf0bd37a70d1d11fa9e49784b6d22e92e8b2f85f18/coverage-7.13.5-cp312-cp312-win_amd64.whl", hash = "sha256:d2c87e0c473a10bffe991502eac389220533024c8082ec1ce849f4218dded810", size = 222900, upload-time = "2026-03-17T10:31:05.651Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/fa/2238c2ad08e35cf4f020ea721f717e09ec3152aea75d191a7faf3ef009a8/coverage-7.13.5-cp312-cp312-win_arm64.whl", hash = "sha256:bf69236a9a81bdca3bff53796237aab096cdbf8d78a66ad61e992d9dac7eb2de", size = 221515, upload-time = "2026-03-17T10:31:07.293Z" },
+    { url = "https://files.pythonhosted.org/packages/74/8c/74fedc9663dcf168b0a059d4ea756ecae4da77a489048f94b5f512a8d0b3/coverage-7.13.5-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5ec4af212df513e399cf11610cc27063f1586419e814755ab362e50a85ea69c1", size = 219576, upload-time = "2026-03-17T10:31:09.045Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/c9/44fb661c55062f0818a6ffd2685c67aa30816200d5f2817543717d4b92eb/coverage-7.13.5-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:941617e518602e2d64942c88ec8499f7fbd49d3f6c4327d3a71d43a1973032f3", size = 219942, upload-time = "2026-03-17T10:31:10.708Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/13/93419671cee82b780bab7ea96b67c8ef448f5f295f36bf5031154ec9a790/coverage-7.13.5-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:da305e9937617ee95c2e39d8ff9f040e0487cbf1ac174f777ed5eddd7a7c1f26", size = 250935, upload-time = "2026-03-17T10:31:12.392Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/68/1666e3a4462f8202d836920114fa7a5ee9275d1fa45366d336c551a162dd/coverage-7.13.5-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:78e696e1cc714e57e8b25760b33a8b1026b7048d270140d25dafe1b0a1ee05a3", size = 253541, upload-time = "2026-03-17T10:31:14.247Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/5e/3ee3b835647be646dcf3c65a7c6c18f87c27326a858f72ab22c12730773d/coverage-7.13.5-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:02ca0eed225b2ff301c474aeeeae27d26e2537942aa0f87491d3e147e784a82b", size = 254780, upload-time = "2026-03-17T10:31:16.193Z" },
+    { url = "https://files.pythonhosted.org/packages/44/b3/cb5bd1a04cfcc49ede6cd8409d80bee17661167686741e041abc7ee1b9a9/coverage-7.13.5-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:04690832cbea4e4663d9149e05dba142546ca05cb1848816760e7f58285c970a", size = 256912, upload-time = "2026-03-17T10:31:17.89Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/66/c1dceb7b9714473800b075f5c8a84f4588f887a90eb8645282031676e242/coverage-7.13.5-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0590e44dd2745c696a778f7bab6aa95256de2cbc8b8cff4f7db8ff09813d6969", size = 251165, upload-time = "2026-03-17T10:31:19.605Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/62/5502b73b97aa2e53ea22a39cf8649ff44827bef76d90bf638777daa27a9d/coverage-7.13.5-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d7cfad2d6d81dd298ab6b89fe72c3b7b05ec7544bdda3b707ddaecff8d25c161", size = 252908, upload-time = "2026-03-17T10:31:21.312Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/37/7792c2d69854397ca77a55c4646e5897c467928b0e27f2d235d83b5d08c6/coverage-7.13.5-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:e092b9499de38ae0fbfbc603a74660eb6ff3e869e507b50d85a13b6db9863e15", size = 250873, upload-time = "2026-03-17T10:31:23.565Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/23/bc866fb6163be52a8a9e5d708ba0d3b1283c12158cefca0a8bbb6e247a43/coverage-7.13.5-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:48c39bc4a04d983a54a705a6389512883d4a3b9862991b3617d547940e9f52b1", size = 255030, upload-time = "2026-03-17T10:31:25.58Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/8b/ef67e1c222ef49860701d346b8bbb70881bef283bd5f6cbba68a39a086c7/coverage-7.13.5-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:2d3807015f138ffea1ed9afeeb8624fd781703f2858b62a8dd8da5a0994c57b6", size = 250694, upload-time = "2026-03-17T10:31:27.316Z" },
+    { url = "https://files.pythonhosted.org/packages/46/0d/866d1f74f0acddbb906db212e096dee77a8e2158ca5e6bb44729f9d93298/coverage-7.13.5-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:ee2aa19e03161671ec964004fb74b2257805d9710bf14a5c704558b9d8dbaf17", size = 252469, upload-time = "2026-03-17T10:31:29.472Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/f5/be742fec31118f02ce42b21c6af187ad6a344fed546b56ca60caacc6a9a0/coverage-7.13.5-cp313-cp313-win32.whl", hash = "sha256:ce1998c0483007608c8382f4ff50164bfc5bd07a2246dd272aa4043b75e61e85", size = 222112, upload-time = "2026-03-17T10:31:31.526Z" },
+    { url = "https://files.pythonhosted.org/packages/66/40/7732d648ab9d069a46e686043241f01206348e2bbf128daea85be4d6414b/coverage-7.13.5-cp313-cp313-win_amd64.whl", hash = "sha256:631efb83f01569670a5e866ceb80fe483e7c159fac6f167e6571522636104a0b", size = 222923, upload-time = "2026-03-17T10:31:33.633Z" },
+    { url = "https://files.pythonhosted.org/packages/48/af/fea819c12a095781f6ccd504890aaddaf88b8fab263c4940e82c7b770124/coverage-7.13.5-cp313-cp313-win_arm64.whl", hash = "sha256:f4cd16206ad171cbc2470dbea9103cf9a7607d5fe8c242fdf1edf36174020664", size = 221540, upload-time = "2026-03-17T10:31:35.445Z" },
+    { url = "https://files.pythonhosted.org/packages/23/d2/17879af479df7fbbd44bd528a31692a48f6b25055d16482fdf5cdb633805/coverage-7.13.5-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:0428cbef5783ad91fe240f673cc1f76b25e74bbfe1a13115e4aa30d3f538162d", size = 220262, upload-time = "2026-03-17T10:31:37.184Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/4c/d20e554f988c8f91d6a02c5118f9abbbf73a8768a3048cb4962230d5743f/coverage-7.13.5-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:e0b216a19534b2427cc201a26c25da4a48633f29a487c61258643e89d28200c0", size = 220617, upload-time = "2026-03-17T10:31:39.245Z" },
+    { url = "https://files.pythonhosted.org/packages/29/9c/f9f5277b95184f764b24e7231e166dfdb5780a46d408a2ac665969416d61/coverage-7.13.5-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:972a9cd27894afe4bc2b1480107054e062df08e671df7c2f18c205e805ccd806", size = 261912, upload-time = "2026-03-17T10:31:41.324Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/f6/7f1ab39393eeb50cfe4747ae8ef0e4fc564b989225aa1152e13a180d74f8/coverage-7.13.5-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:4b59148601efcd2bac8c4dbf1f0ad6391693ccf7a74b8205781751637076aee3", size = 263987, upload-time = "2026-03-17T10:31:43.724Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/d7/62c084fb489ed9c6fbdf57e006752e7c516ea46fd690e5ed8b8617c7d52e/coverage-7.13.5-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:505d7083c8b0c87a8fa8c07370c285847c1f77739b22e299ad75a6af6c32c5c9", size = 266416, upload-time = "2026-03-17T10:31:45.769Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/f6/df63d8660e1a0bff6125947afda112a0502736f470d62ca68b288ea762d8/coverage-7.13.5-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:60365289c3741e4db327e7baff2a4aaacf22f788e80fa4683393891b70a89fbd", size = 267558, upload-time = "2026-03-17T10:31:48.293Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/02/353ca81d36779bd108f6d384425f7139ac3c58c750dcfaafe5d0bee6436b/coverage-7.13.5-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:1b88c69c8ef5d4b6fe7dea66d6636056a0f6a7527c440e890cf9259011f5e606", size = 261163, upload-time = "2026-03-17T10:31:50.125Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/16/2e79106d5749bcaf3aee6d309123548e3276517cd7851faa8da213bc61bf/coverage-7.13.5-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:5b13955d31d1633cf9376908089b7cebe7d15ddad7aeaabcbe969a595a97e95e", size = 263981, upload-time = "2026-03-17T10:31:51.961Z" },
+    { url = "https://files.pythonhosted.org/packages/29/c7/c29e0c59ffa6942030ae6f50b88ae49988e7e8da06de7ecdbf49c6d4feae/coverage-7.13.5-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:f70c9ab2595c56f81a89620e22899eea8b212a4041bd728ac6f4a28bf5d3ddd0", size = 261604, upload-time = "2026-03-17T10:31:53.872Z" },
+    { url = "https://files.pythonhosted.org/packages/40/48/097cdc3db342f34006a308ab41c3a7c11c3f0d84750d340f45d88a782e00/coverage-7.13.5-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:084b84a8c63e8d6fc7e3931b316a9bcafca1458d753c539db82d31ed20091a87", size = 265321, upload-time = "2026-03-17T10:31:55.997Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/1f/4994af354689e14fd03a75f8ec85a9a68d94e0188bbdab3fc1516b55e512/coverage-7.13.5-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:ad14385487393e386e2ea988b09d62dd42c397662ac2dabc3832d71253eee479", size = 260502, upload-time = "2026-03-17T10:31:58.308Z" },
+    { url = "https://files.pythonhosted.org/packages/22/c6/9bb9ef55903e628033560885f5c31aa227e46878118b63ab15dc7ba87797/coverage-7.13.5-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:7f2c47b36fe7709a6e83bfadf4eefb90bd25fbe4014d715224c4316f808e59a2", size = 262688, upload-time = "2026-03-17T10:32:00.141Z" },
+    { url = "https://files.pythonhosted.org/packages/14/4f/f5df9007e50b15e53e01edea486814783a7f019893733d9e4d6caad75557/coverage-7.13.5-cp313-cp313t-win32.whl", hash = "sha256:67e9bc5449801fad0e5dff329499fb090ba4c5800b86805c80617b4e29809b2a", size = 222788, upload-time = "2026-03-17T10:32:02.246Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/98/aa7fccaa97d0f3192bec013c4e6fd6d294a6ed44b640e6bb61f479e00ed5/coverage-7.13.5-cp313-cp313t-win_amd64.whl", hash = "sha256:da86cdcf10d2519e10cabb8ac2de03da1bcb6e4853790b7fbd48523332e3a819", size = 223851, upload-time = "2026-03-17T10:32:04.416Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/8b/e5c469f7352651e5f013198e9e21f97510b23de957dd06a84071683b4b60/coverage-7.13.5-cp313-cp313t-win_arm64.whl", hash = "sha256:0ecf12ecb326fe2c339d93fc131816f3a7367d223db37817208905c89bded911", size = 222104, upload-time = "2026-03-17T10:32:06.65Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/77/39703f0d1d4b478bfd30191d3c14f53caf596fac00efb3f8f6ee23646439/coverage-7.13.5-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:fbabfaceaeb587e16f7008f7795cd80d20ec548dc7f94fbb0d4ec2e038ce563f", size = 219621, upload-time = "2026-03-17T10:32:08.589Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/3e/51dff36d99ae14639a133d9b164d63e628532e2974d8b1edb99dd1ebc733/coverage-7.13.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:9bb2a28101a443669a423b665939381084412b81c3f8c0fcfbac57f4e30b5b8e", size = 219953, upload-time = "2026-03-17T10:32:10.507Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/6c/1f1917b01eb647c2f2adc9962bd66c79eb978951cab61bdc1acab3290c07/coverage-7.13.5-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:bd3a2fbc1c6cccb3c5106140d87cc6a8715110373ef42b63cf5aea29df8c217a", size = 250992, upload-time = "2026-03-17T10:32:12.41Z" },
+    { url = "https://files.pythonhosted.org/packages/22/e5/06b1f88f42a5a99df42ce61208bdec3bddb3d261412874280a19796fc09c/coverage-7.13.5-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6c36ddb64ed9d7e496028d1d00dfec3e428e0aabf4006583bb1839958d280510", size = 253503, upload-time = "2026-03-17T10:32:14.449Z" },
+    { url = "https://files.pythonhosted.org/packages/80/28/2a148a51e5907e504fa7b85490277734e6771d8844ebcc48764a15e28155/coverage-7.13.5-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:380e8e9084d8eb38db3a9176a1a4f3c0082c3806fa0dc882d1d87abc3c789247", size = 254852, upload-time = "2026-03-17T10:32:16.56Z" },
+    { url = "https://files.pythonhosted.org/packages/61/77/50e8d3d85cc0b7ebe09f30f151d670e302c7ff4a1bf6243f71dd8b0981fa/coverage-7.13.5-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e808af52a0513762df4d945ea164a24b37f2f518cbe97e03deaa0ee66139b4d6", size = 257161, upload-time = "2026-03-17T10:32:19.004Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/c4/b5fd1d4b7bf8d0e75d997afd3925c59ba629fc8616f1b3aae7605132e256/coverage-7.13.5-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e301d30dd7e95ae068671d746ba8c34e945a82682e62918e41b2679acd2051a0", size = 251021, upload-time = "2026-03-17T10:32:21.344Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/66/6ea21f910e92d69ef0b1c3346ea5922a51bad4446c9126db2ae96ee24c4c/coverage-7.13.5-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:800bc829053c80d240a687ceeb927a94fd108bbdc68dfbe505d0d75ab578a882", size = 252858, upload-time = "2026-03-17T10:32:23.506Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/ea/879c83cb5d61aa2a35fb80e72715e92672daef8191b84911a643f533840c/coverage-7.13.5-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:0b67af5492adb31940ee418a5a655c28e48165da5afab8c7fa6fd72a142f8740", size = 250823, upload-time = "2026-03-17T10:32:25.516Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/fb/616d95d3adb88b9803b275580bdeee8bd1b69a886d057652521f83d7322f/coverage-7.13.5-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:c9136ff29c3a91e25b1d1552b5308e53a1e0653a23e53b6366d7c2dcbbaf8a16", size = 255099, upload-time = "2026-03-17T10:32:27.944Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/93/25e6917c90ec1c9a56b0b26f6cad6408e5f13bb6b35d484a0d75c9cf000d/coverage-7.13.5-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:cff784eef7f0b8f6cb28804fbddcfa99f89efe4cc35fb5627e3ac58f91ed3ac0", size = 250638, upload-time = "2026-03-17T10:32:29.914Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/7b/dc1776b0464145a929deed214aef9fb1493f159b59ff3c7eeeedf91eddd0/coverage-7.13.5-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:68a4953be99b17ac3c23b6efbc8a38330d99680c9458927491d18700ef23ded0", size = 252295, upload-time = "2026-03-17T10:32:31.981Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/fb/99cbbc56a26e07762a2740713f3c8f9f3f3106e3a3dd8cc4474954bccd34/coverage-7.13.5-cp314-cp314-win32.whl", hash = "sha256:35a31f2b1578185fbe6aa2e74cea1b1d0bbf4c552774247d9160d29b80ed56cc", size = 222360, upload-time = "2026-03-17T10:32:34.233Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/b7/4758d4f73fb536347cc5e4ad63662f9d60ba9118cb6785e9616b2ce5d7fa/coverage-7.13.5-cp314-cp314-win_amd64.whl", hash = "sha256:2aa055ae1857258f9e0045be26a6d62bdb47a72448b62d7b55f4820f361a2633", size = 223174, upload-time = "2026-03-17T10:32:36.369Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/f2/24d84e1dfe70f8ac9fdf30d338239860d0d1d5da0bda528959d0ebc9da28/coverage-7.13.5-cp314-cp314-win_arm64.whl", hash = "sha256:1b11eef33edeae9d142f9b4358edb76273b3bfd30bc3df9a4f95d0e49caf94e8", size = 221739, upload-time = "2026-03-17T10:32:38.736Z" },
+    { url = "https://files.pythonhosted.org/packages/60/5b/4a168591057b3668c2428bff25dd3ebc21b629d666d90bcdfa0217940e84/coverage-7.13.5-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:10a0c37f0b646eaff7cce1874c31d1f1ccb297688d4c747291f4f4c70741cc8b", size = 220351, upload-time = "2026-03-17T10:32:41.196Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/21/1fd5c4dbfe4a58b6b99649125635df46decdfd4a784c3cd6d410d303e370/coverage-7.13.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b5db73ba3c41c7008037fa731ad5459fc3944cb7452fc0aa9f822ad3533c583c", size = 220612, upload-time = "2026-03-17T10:32:43.204Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/fe/2a924b3055a5e7e4512655a9d4609781b0d62334fa0140c3e742926834e2/coverage-7.13.5-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:750db93a81e3e5a9831b534be7b1229df848b2e125a604fe6651e48aa070e5f9", size = 261985, upload-time = "2026-03-17T10:32:45.514Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/0d/c8928f2bd518c45990fe1a2ab8db42e914ef9b726c975facc4282578c3eb/coverage-7.13.5-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:9ddb4f4a5479f2539644be484da179b653273bca1a323947d48ab107b3ed1f29", size = 264107, upload-time = "2026-03-17T10:32:47.971Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/ae/4ae35bbd9a0af9d820362751f0766582833c211224b38665c0f8de3d487f/coverage-7.13.5-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d8a7a2049c14f413163e2bdabd37e41179b1d1ccb10ffc6ccc4b7a718429c607", size = 266513, upload-time = "2026-03-17T10:32:50.1Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/20/d326174c55af36f74eac6ae781612d9492f060ce8244b570bb9d50d9d609/coverage-7.13.5-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e1c85e0b6c05c592ea6d8768a66a254bfb3874b53774b12d4c89c481eb78cb90", size = 267650, upload-time = "2026-03-17T10:32:52.391Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/5e/31484d62cbd0eabd3412e30d74386ece4a0837d4f6c3040a653878bfc019/coverage-7.13.5-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:777c4d1eff1b67876139d24288aaf1817f6c03d6bae9c5cc8d27b83bcfe38fe3", size = 261089, upload-time = "2026-03-17T10:32:54.544Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/d8/49a72d6de146eebb0b7e48cc0f4bc2c0dd858e3d4790ab2b39a2872b62bd/coverage-7.13.5-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:6697e29b93707167687543480a40f0db8f356e86d9f67ddf2e37e2dfd91a9dab", size = 263982, upload-time = "2026-03-17T10:32:56.803Z" },
+    { url = "https://files.pythonhosted.org/packages/06/3b/0351f1bd566e6e4dd39e978efe7958bde1d32f879e85589de147654f57bb/coverage-7.13.5-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:8fdf453a942c3e4d99bd80088141c4c6960bb232c409d9c3558e2dbaa3998562", size = 261579, upload-time = "2026-03-17T10:32:59.466Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/ce/796a2a2f4017f554d7810f5c573449b35b1e46788424a548d4d19201b222/coverage-7.13.5-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:32ca0c0114c9834a43f045a87dcebd69d108d8ffb666957ea65aa132f50332e2", size = 265316, upload-time = "2026-03-17T10:33:01.847Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/16/d5ae91455541d1a78bc90abf495be600588aff8f6db5c8b0dae739fa39c9/coverage-7.13.5-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:8769751c10f339021e2638cd354e13adeac54004d1941119b2c96fe5276d45ea", size = 260427, upload-time = "2026-03-17T10:33:03.945Z" },
+    { url = "https://files.pythonhosted.org/packages/48/11/07f413dba62db21fb3fad5d0de013a50e073cc4e2dc4306e770360f6dfc8/coverage-7.13.5-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:cec2d83125531bd153175354055cdb7a09987af08a9430bd173c937c6d0fba2a", size = 262745, upload-time = "2026-03-17T10:33:06.285Z" },
+    { url = "https://files.pythonhosted.org/packages/91/15/d792371332eb4663115becf4bad47e047d16234b1aff687b1b18c58d60ae/coverage-7.13.5-cp314-cp314t-win32.whl", hash = "sha256:0cd9ed7a8b181775459296e402ca4fb27db1279740a24e93b3b41942ebe4b215", size = 223146, upload-time = "2026-03-17T10:33:08.756Z" },
+    { url = "https://files.pythonhosted.org/packages/db/51/37221f59a111dca5e85be7dbf09696323b5b9f13ff65e0641d535ed06ea8/coverage-7.13.5-cp314-cp314t-win_amd64.whl", hash = "sha256:301e3b7dfefecaca37c9f1aa6f0049b7d4ab8dd933742b607765d757aca77d43", size = 224254, upload-time = "2026-03-17T10:33:11.174Z" },
+    { url = "https://files.pythonhosted.org/packages/54/83/6acacc889de8987441aa7d5adfbdbf33d288dad28704a67e574f1df9bcbb/coverage-7.13.5-cp314-cp314t-win_arm64.whl", hash = "sha256:9dacc2ad679b292709e0f5fc1ac74a6d4d5562e424058962c7bb0c658ad25e45", size = 222276, upload-time = "2026-03-17T10:33:13.466Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/ee/a4cf96b8ce1e566ed238f0659ac2d3f007ed1d14b181bcb684e19561a69a/coverage-7.13.5-py3-none-any.whl", hash = "sha256:34b02417cf070e173989b3db962f7ed56d2f644307b2cf9d5a0f258e13084a61", size = 211346, upload-time = "2026-03-17T10:33:15.691Z" },
+]
+
 [[package]]
 name = "croniter"
 version = "6.0.0"
@@ -573,6 +661,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" },
 ]
 
+[[package]]
+name = "pytest-cov"
+version = "7.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "coverage" },
+    { name = "pluggy" },
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5e/f7/c933acc76f5208b3b00089573cf6a2bc26dc80a8aece8f52bb7d6b1855ca/pytest_cov-7.0.0.tar.gz", hash = "sha256:33c97eda2e049a0c5298e91f519302a1334c26ac65c1a483d6206fd458361af1", size = 54328, upload-time = "2025-09-09T10:57:02.113Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ee/49/1377b49de7d0c1ce41292161ea0f721913fa8722c19fb9c1e3aa0367eecb/pytest_cov-7.0.0-py3-none-any.whl", hash = "sha256:3b8e9558b16cc1479da72058bdecf8073661c7f57f7d3c5f22a1c23507f2d861", size = 22424, upload-time = "2025-09-09T10:57:00.695Z" },
+]
+
 [[package]]
 name = "python-dateutil"
 version = "2.9.0.post0"
@@ -720,6 +822,31 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/14/25/b208c5683343959b670dc001595f2f3737e051da617f66c31f7c4fa93abc/rich-14.3.3-py3-none-any.whl", hash = "sha256:793431c1f8619afa7d3b52b2cdec859562b950ea0d4b6b505397612db8d5362d", size = 310458, upload-time = "2026-02-19T17:23:13.732Z" },
 ]
 
+[[package]]
+name = "ruff"
+version = "0.15.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/51/df/f8629c19c5318601d3121e230f74cbee7a3732339c52b21daa2b82ef9c7d/ruff-0.15.6.tar.gz", hash = "sha256:8394c7bb153a4e3811a4ecdacd4a8e6a4fa8097028119160dffecdcdf9b56ae4", size = 4597916, upload-time = "2026-03-12T23:05:47.51Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9e/2f/4e03a7e5ce99b517e98d3b4951f411de2b0fa8348d39cf446671adcce9a2/ruff-0.15.6-py3-none-linux_armv6l.whl", hash = "sha256:7c98c3b16407b2cf3d0f2b80c80187384bc92c6774d85fefa913ecd941256fff", size = 10508953, upload-time = "2026-03-12T23:05:17.246Z" },
+    { url = "https://files.pythonhosted.org/packages/70/60/55bcdc3e9f80bcf39edf0cd272da6fa511a3d94d5a0dd9e0adf76ceebdb4/ruff-0.15.6-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:ee7dcfaad8b282a284df4aa6ddc2741b3f4a18b0555d626805555a820ea181c3", size = 10942257, upload-time = "2026-03-12T23:05:23.076Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/f9/005c29bd1726c0f492bfa215e95154cf480574140cb5f867c797c18c790b/ruff-0.15.6-py3-none-macosx_11_0_arm64.whl", hash = "sha256:3bd9967851a25f038fc8b9ae88a7fbd1b609f30349231dffaa37b6804923c4bb", size = 10322683, upload-time = "2026-03-12T23:05:33.738Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/74/2f861f5fd7cbb2146bddb5501450300ce41562da36d21868c69b7a828169/ruff-0.15.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:13f4594b04e42cd24a41da653886b04d2ff87adbf57497ed4f728b0e8a4866f8", size = 10660986, upload-time = "2026-03-12T23:05:53.245Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/a1/309f2364a424eccb763cdafc49df843c282609f47fe53aa83f38272389e0/ruff-0.15.6-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e2ed8aea2f3fe57886d3f00ea5b8aae5bf68d5e195f487f037a955ff9fbaac9e", size = 10332177, upload-time = "2026-03-12T23:05:56.145Z" },
+    { url = "https://files.pythonhosted.org/packages/30/41/7ebf1d32658b4bab20f8ac80972fb19cd4e2c6b78552be263a680edc55ac/ruff-0.15.6-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:70789d3e7830b848b548aae96766431c0dc01a6c78c13381f423bf7076c66d15", size = 11170783, upload-time = "2026-03-12T23:06:01.742Z" },
+    { url = "https://files.pythonhosted.org/packages/76/be/6d488f6adca047df82cd62c304638bcb00821c36bd4881cfca221561fdfc/ruff-0.15.6-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:542aaf1de3154cea088ced5a819ce872611256ffe2498e750bbae5247a8114e9", size = 12044201, upload-time = "2026-03-12T23:05:28.697Z" },
+    { url = "https://files.pythonhosted.org/packages/71/68/e6f125df4af7e6d0b498f8d373274794bc5156b324e8ab4bf5c1b4fc0ec7/ruff-0.15.6-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:1c22e6f02c16cfac3888aa636e9eba857254d15bbacc9906c9689fdecb1953ab", size = 11421561, upload-time = "2026-03-12T23:05:31.236Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/9f/f85ef5fd01a52e0b472b26dc1b4bd228b8f6f0435975442ffa4741278703/ruff-0.15.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:98893c4c0aadc8e448cfa315bd0cc343a5323d740fe5f28ef8a3f9e21b381f7e", size = 11310928, upload-time = "2026-03-12T23:05:45.288Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/26/b75f8c421f5654304b89471ed384ae8c7f42b4dff58fa6ce1626d7f2b59a/ruff-0.15.6-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:70d263770d234912374493e8cc1e7385c5d49376e41dfa51c5c3453169dc581c", size = 11235186, upload-time = "2026-03-12T23:05:50.677Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/d4/d5a6d065962ff7a68a86c9b4f5500f7d101a0792078de636526c0edd40da/ruff-0.15.6-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:55a1ad63c5a6e54b1f21b7514dfadc0c7fb40093fa22e95143cf3f64ebdcd512", size = 10635231, upload-time = "2026-03-12T23:05:37.044Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/56/7c3acf3d50910375349016cf33de24be021532042afbed87942858992491/ruff-0.15.6-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8dc473ba093c5ec238bb1e7429ee676dca24643c471e11fbaa8a857925b061c0", size = 10340357, upload-time = "2026-03-12T23:06:04.748Z" },
+    { url = "https://files.pythonhosted.org/packages/06/54/6faa39e9c1033ff6a3b6e76b5df536931cd30caf64988e112bbf91ef5ce5/ruff-0.15.6-py3-none-musllinux_1_2_i686.whl", hash = "sha256:85b042377c2a5561131767974617006f99f7e13c63c111b998f29fc1e58a4cfb", size = 10860583, upload-time = "2026-03-12T23:05:58.978Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/1e/509a201b843b4dfb0b32acdedf68d951d3377988cae43949ba4c4133a96a/ruff-0.15.6-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:cef49e30bc5a86a6a92098a7fbf6e467a234d90b63305d6f3ec01225a9d092e0", size = 11410976, upload-time = "2026-03-12T23:05:39.955Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/25/3fc9114abf979a41673ce877c08016f8e660ad6cf508c3957f537d2e9fa9/ruff-0.15.6-py3-none-win32.whl", hash = "sha256:bbf67d39832404812a2d23020dda68fee7f18ce15654e96fb1d3ad21a5fe436c", size = 10616872, upload-time = "2026-03-12T23:05:42.451Z" },
+    { url = "https://files.pythonhosted.org/packages/89/7a/09ece68445ceac348df06e08bf75db72d0e8427765b96c9c0ffabc1be1d9/ruff-0.15.6-py3-none-win_amd64.whl", hash = "sha256:aee25bc84c2f1007ecb5037dff75cef00414fdf17c23f07dc13e577883dca406", size = 11787271, upload-time = "2026-03-12T23:05:20.168Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/d0/578c47dd68152ddddddf31cd7fc67dc30b7cdf639a86275fda821b0d9d98/ruff-0.15.6-py3-none-win_arm64.whl", hash = "sha256:c34de3dd0b0ba203be50ae70f5910b17188556630e2178fd7d79fc030eb0d837", size = 11060497, upload-time = "2026-03-12T23:05:25.968Z" },
+]
+
 [[package]]
 name = "setuptools"
 version = "82.0.0"

From 23c63e1a8b361f5a1c81ba5446ac0d55e1e76439 Mon Sep 17 00:00:00 2001
From: hetaoBackend <hetao7@pku.edu.cn>
Date: Wed, 18 Mar 2026 16:10:12 +0800
Subject: [PATCH 3/4] fix: stabilize forwarded message timestamps

---
 channels/feishu_channel.py   |  7 ++++---
 channels/telegram_channel.py |  7 ++++---
 docs/todo.md                 | 10 ++++++++++
 3 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/channels/feishu_channel.py b/channels/feishu_channel.py
index 2c26a2c..4027dfb 100644
--- a/channels/feishu_channel.py
+++ b/channels/feishu_channel.py
@@ -15,6 +15,7 @@
 import base64
 import json
 import threading
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import TYPE_CHECKING, Optional
 
@@ -545,9 +546,9 @@ def _format_forwarded_prompt(self, original_content: str, forwarded: dict) -> st
         parts.append(f"转发自: {sender_name}")
 
         if forwarded.get("timestamp"):
-            from datetime import datetime
-
-            ts = datetime.fromtimestamp(forwarded["timestamp"])
+            ts = datetime.fromtimestamp(
+                forwarded["timestamp"], tz=timezone(timedelta(hours=8))
+            )
             parts.append(f"时间: {ts.strftime('%Y-%m-%d %H:%M')}")
 
         parts.append("\n--- 转发内容 ---")
diff --git a/channels/telegram_channel.py b/channels/telegram_channel.py
index 0578d0e..d81ee8e 100644
--- a/channels/telegram_channel.py
+++ b/channels/telegram_channel.py
@@ -22,6 +22,7 @@
 import asyncio
 import os
 import threading
+from datetime import datetime, timedelta, timezone
 from typing import TYPE_CHECKING, Optional
 
 try:
@@ -324,9 +325,9 @@ def _format_forwarded_text(self, text: str, update: "Update") -> str:
 
         # 添加时间戳
         if msg.forward_date:
-            from datetime import datetime
-
-            ts = datetime.fromtimestamp(msg.forward_date)
+            ts = datetime.fromtimestamp(
+                msg.forward_date, tz=timezone(timedelta(hours=8))
+            )
             parts.append(f"时间: {ts.strftime('%Y-%m-%d %H:%M')}")
 
         parts.append("\n--- 转发内容 ---")
diff --git a/docs/todo.md b/docs/todo.md
index 2eb246e..c1ac1e3 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -2,6 +2,16 @@
 
 ## In Progress
 
+- [x] **修复转发消息时间格式测试失败** — 统一 Feishu / Telegram 转发时间按北京时间 `UTC+8` 格式化
+  - ✅ 已修复：`channels/feishu_channel.py` 与 `channels/telegram_channel.py` 不再依赖进程本地时区
+  - ✅ 验证：相关 3 个失败用例通过；`tests/test_feishu_forwarded_messages.py` 和 `tests/test_telegram_forwarded_messages.py` 全部通过
+- [x] **rebase `codex/backend-quality-and-heartbeat` onto latest `origin/main`** — 解决 PR #6 的文本冲突并保留 heartbeat + backend quality baseline 改动
+  - ✅ 已完成：`git rebase origin/main` 成功，`9ae1cdd` 被自动识别为已在上游并 dropped
+  - ✅ 已确认：`git merge-base HEAD origin/main` 与 `origin/main` 均为 `6aeb72e`
+  - ✅ 验证：`make check` 通过，`54 passed`
+- [x] **检查并处理当前分支的 merge conflicts** — 核对 git merge/rebase 状态、未合并文件以及与 `main` 的分叉点
+  - ✅ 已确认：当前无进行中的 merge/rebase，`git diff --name-only --diff-filter=U` 为空
+  - ✅ 已确认：`HEAD`、`main`、`merge-base` 均为 `626f16b`，当前工作树 clean
 - [x] **建立后端 lint/test/CI 基线** — 为 Python 后端接入 `ruff`、`pytest` 覆盖率和 GitHub Actions 质量门禁
   - ✅ 已完成：`pyproject.toml` 新增 `ruff` / `pytest-cov` 与 lint、pytest、coverage 配置
   - ✅ 已完成：`Makefile` 新增 `lint` / `format` / `format-check` / `test` / `test-cov` / `check`

From ad2332cd686ead9d270c7205a0049c302a3cb39c Mon Sep 17 00:00:00 2001
From: hetaoBackend <hetao7@pku.edu.cn>
Date: Wed, 18 Mar 2026 16:12:44 +0800
Subject: [PATCH 4/4] fix lint

---
 channels/feishu_channel.py   | 4 +---
 channels/telegram_channel.py | 4 +---
 2 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/channels/feishu_channel.py b/channels/feishu_channel.py
index 4027dfb..9e971c6 100644
--- a/channels/feishu_channel.py
+++ b/channels/feishu_channel.py
@@ -546,9 +546,7 @@ def _format_forwarded_prompt(self, original_content: str, forwarded: dict) -> st
         parts.append(f"转发自: {sender_name}")
 
         if forwarded.get("timestamp"):
-            ts = datetime.fromtimestamp(
-                forwarded["timestamp"], tz=timezone(timedelta(hours=8))
-            )
+            ts = datetime.fromtimestamp(forwarded["timestamp"], tz=timezone(timedelta(hours=8)))
             parts.append(f"时间: {ts.strftime('%Y-%m-%d %H:%M')}")
 
         parts.append("\n--- 转发内容 ---")
diff --git a/channels/telegram_channel.py b/channels/telegram_channel.py
index d81ee8e..d4a1c78 100644
--- a/channels/telegram_channel.py
+++ b/channels/telegram_channel.py
@@ -325,9 +325,7 @@ def _format_forwarded_text(self, text: str, update: "Update") -> str:
 
         # 添加时间戳
         if msg.forward_date:
-            ts = datetime.fromtimestamp(
-                msg.forward_date, tz=timezone(timedelta(hours=8))
-            )
+            ts = datetime.fromtimestamp(msg.forward_date, tz=timezone(timedelta(hours=8)))
             parts.append(f"时间: {ts.strftime('%Y-%m-%d %H:%M')}")
 
         parts.append("\n--- 转发内容 ---")