[codex] Fix agent background progress surfaces

[utopiafar]

背景

Fixes #267。

这次 PR 聚焦修复后台 Agent 进度展示链路：Android 通知、iOS background bridge、以及 App 内浮动的 Agent activity widget 之前会各自读取不同的 transient activity / task snapshot，导致通知文本滞后、部分文案未本地化，以及从通知返回 App 时在缺少 live activity 历史的情况下无法稳定恢复进度。

本 PR 有意只收敛通知与进度语义，不重做 Agent Core，也不拆分 agent handler。更系统性的 SQLite executor ownership / foreground-background lease 问题继续由 #268 跟踪。

主要改动

• 新增持久化 agent_runs 状态表，并把队列任务关联到同一个 run_id，让一次用户提交对应一个可恢复的进度面。
• 统一 AgentBackgroundStatus 语义，供 Android 通知、iOS background status payload、以及前台 Agent activity widget 复用。
• 将原先偏百分比的通知文本替换为本地化的 running / pending / retry 任务摘要。
• 补齐 zh/en 本地化 key，包括后台 Agent 标题、阶段、任务摘要、暂停/失败/完成说明。
• 从通知返回或正常启动 App 时，即使 transient activity 记录缺失，也能通过 durable run 状态保持浮动入口可见。
• 让 crash-guard marker 清理和 agent activity 持久化更能容忍短暂 SQLite database is locked，避免非关键进度路径冒出未处理 Flutter 异常。
• 用户输入 enqueue 出任务后立即触发 Android queue drain，同时保留生命周期触发作为 fallback。

本轮更新

• 已合入最新 upstream/main（base 4b20327），并解决 merge conflicts；当前 PR 为 MERGEABLE。
• 修复 AI Review 提到的 submitInput 风险：durable AgentRunService 创建/刷新失败时只记录 warning，不再阻塞用户提交链路。
• 新增 submitInput 回归测试，覆盖 durable run 写入失败但 fact/card 仍落盘的路径。
• 新增 schema 14→15 migration test：用真实 schema 14 sqlite 文件触发当前 Drift upgrade，验证：
  • tasks.run_id nullable 列会被添加；
  • idx_tasks_run_id 会被创建；
  • agent_runs 表可写；
  • 旧任务的 NULL run_id 保持安全，不会污染新 durable run 的 remainingTasks 统计。

已知后续

#268 继续跟踪系统性的 SQLite contention / 单 executor owner 设计。本 PR 已经让非关键进度/marker 路径更稳，但前后台 executor lease、WAL/busy timeout 验证、集中式 DB retry policy 仍建议单独设计，不放进本 PR 扩大范围。

验证

本轮补充验证：

• git diff --check
• flutter analyze --no-pub --no-fatal-infos
  • 通过；仓库仍有既有 info 级 lint noise（287）。
• flutter test --no-pub test/db/app_database_migration_test.dart
• flutter test --no-pub test/db/app_database_migration_test.dart test/data/services/agent_run_service_test.dart test/data/services/local_task_executor_test.dart test/data/repositories/submit_input_test.dart
• flutter test --no-pub --concurrency=1
  • 通过：540 passed，7 skipped。

PR 原有验证记录：

• flutter test test/data/services/agent_run_service_test.dart test/data/services/agent_background_status_test.dart test/data/services/agent_background_coordinator_test.dart test/data/services/agent_queue_background_worker_test.dart test/data/services/local_task_executor_test.dart test/ui/agent_activity/agent_activity_widget_test.dart
• flutter build apk --debug --flavor globalDev
• Android real-device log spot check on com.memexlab.memex.dev：
  • crash buffer 中没有当前 Memex crash；
  • 没有此前 crash-guard cleanup 路径的 E/flutter ... Unhandled Exception；
  • 剩余 SQLite queue-drain retry 已记录到 Design single-owner SQLite access for background agent queue #268。

当前状态

• PR 仍保持 Draft，等待最终人工确认是否 ready for review。
• 最新 head：9f9abe7。
• GitHub checks 已全部通过：PR AI Review、Flutter Analyze and Test、PR Policy Preflight。

[github-actions]

PR AI Review / PR AI 语义预检

中文

• 风险等级：高风险
• 需要人工审核：是
• 黄金链路影响：已确认
• 置信度：medium
• Workflow run：27433191593

本次 PR 新增 agent_runs 持久化状态表，统一 Android 通知、iOS background bridge 和前台 Agent activity widget 的进度语义。改动覆盖数据库 schema 迁移（14→15）、新增 AgentRunService、扩展 AgentBackgroundStatus 状态模型、修改 submitInput 链路、以及在 LocalTaskExecutor 中接入 run 生命周期钩子。diff 超过 220KB 被截断，部分 test 和 generated 代码无法完整验证。PR 提供了较充分的测试证据（540 passed, 7 skipped），但 Android 通知文案存在硬编码英文、_isDatabaseLocked 检测模式不一致等问题需关注。

影响范围

• database
• service
• repository
• platform_android
• platform_ios
• i18n
• ui
• tests

黄金链路

• agent_pipeline
• record_capture
• local_first_data
• platform_entry
• 说明：新增 agent_runs 持久化表并改变 LocalTaskExecutor 生命周期，直接影响 agent 任务调度、submitInput 用户提交链路、以及 Android/iOS 后台进度展示。数据库 schema 从 14 迁移到 15，涉及跨层变更（DB → service → repository → platform channel）。

风险项

• high Diff 被截断，无法完整审查所有变更。证据：pr-policy-preflight.json: diff_truncated=true, diff_bytes=462361, pr-diff.patch 截断于 app_database.g.dart 生成代码中间, 31 个变更文件中 l10n 生成文件、UI widget、部分 test 文件的变更未完整展示。
  建议：人工审核者应重点关注截断部分：app_localizations.dart/en/zh 生成文件、agent_activity_widget.dart UI 变更、以及所有新增/修改的 test 文件内容是否完整。
• warn Android 通知 taskSummaryFromCounts 使用硬编码英文。证据：AgentBackgroundService.kt:208-210: taskSummaryFromCounts returns "Running $processing, Pending $pending, Retry $retrying", iOS subtitle() 通过 statusText 传入已本地化文本，但 Android fallback 未走同样路径。
  建议：将 taskSummaryFromCounts 的格式化字符串改为从 Flutter 侧传入已本地化的 taskSummary，避免 Android 原生层产生未本地化通知文案。PR 已通过 statusText 字段传递本地化文本，但 fallback 路径仍用硬编码英文。
• warn _isDatabaseLocked 检测模式在多个文件中不一致。证据：agent_activity_service.dart: 检测 'database is locked', 'sqliteexception(5)', 'database_busy', local_task_executor.dart: 检测 'database is locked', 'sqliteexception(5)', 'database_busy', agent_queue_background_worker.dart: 检测 'database is locked', 'sqliteexception(5)', 'code 5'。
  建议：将 _isDatabaseLocked 提取为共享工具函数，统一检测模式。当前三个文件各自实现，模式略有差异（'database_busy' vs 'code 5'），可能导致某些 SQLite lock 场景在部分路径被遗漏。
• warn _localizeKnownStatusText 依赖硬编码英文匹配，脆弱性较高。证据：agent_background_status.dart: _localizeKnownStatusText 使用 switch 匹配 'Idle', 'Processing', 'Queued' 等英文字符串, 新增 stage 或变更 stage 文案时需要同步更新此映射。
  建议：考虑使用枚举 key 而非英文字符串作为 stage 的内部标识，仅在最终展示时映射到本地化文本。当前实现可用但维护成本较高。
• info submitInput 中直接实例化 WorkmanagerAgentQueueDrainScheduler。证据：submit_input.dart: WorkmanagerAgentQueueDrainScheduler().schedule(expedited: true), AGENTS.md 规定: dependencies.dart 只注册 repository/service，通过 MemexRouter 访问。
  建议：当前实现可接受（scheduler 是轻量无状态工具），但如果后续需要 mock 或替换调度策略，建议通过注入方式提供。

测试缺口

• lib/data/services/agent_run_service.dart AgentRunService 是全新服务（508 行），PR 声称有 agent_run_service_test.dart（209 行），但因 diff 截断无法验证测试覆盖范围是否充分（如 markActiveRunsPausedBySystem、resumePausedRunIfNeeded、_refreshRunFromTasks 边界情况）。。 建议检查：Review test/data/services/agent_run_service_test.dart for coverage of all public methods and state transitions.。
• lib/ui/agent_activity/widgets/agent_activity_widget.dart agent_activity_widget.dart 有 +64/-9 行变更，PR 声称有 widget test 更新，但 diff 截断无法验证 UI 渲染测试是否覆盖新增的进度展示逻辑（progressCompleted/progressTotal 显示、paused 状态展示）。。 建议检查：Review test/ui/agent_activity/agent_activity_widget_test.dart for paused state and progress bar rendering assertions.。
• lib/db/app_database.dart (schema 14→15 migration) PR 声称有 app_database_migration_test.dart（139 行）验证 schema 迁移，但 diff 截断无法确认测试是否覆盖：已有数据在迁移后 run_id 为 NULL 的兼容性、以及从 schema 13 或更早版本直接升级到 15 的路径。。 建议检查：Review test/db/app_database_migration_test.dart for multi-version upgrade paths and NULL run_id data integrity.。

English

• Risk level: HIGH
• Human review required: YES
• Golden path impact: CONFIRMED
• Confidence: medium
• Workflow run: 27433191593

This PR introduces a durable agent_runs state table and unifies progress semantics across Android notifications, iOS background bridge, and the in-app Agent activity widget. Changes span DB schema migration (14→15), new AgentRunService, expanded AgentBackgroundStatus model, modified submitInput path, and run lifecycle hooks in LocalTaskExecutor. The diff exceeded 220KB and was truncated, so some test and generated code could not be fully verified. The PR provides substantial test evidence (540 passed, 7 skipped), but hardcoded English in Android notifications and inconsistent _isDatabaseLocked detection patterns warrant attention.

Affected Areas

• database
• service
• repository
• platform_android
• platform_ios
• i18n
• ui
• tests

Golden Path

• agent_pipeline
• record_capture
• local_first_data
• platform_entry
• Rationale: New durable agent_runs table and changes to LocalTaskExecutor lifecycle directly affect agent task scheduling, the submitInput user submission path, and Android/iOS background progress surfaces. Database schema migrates from 14 to 15 with cross-layer changes (DB → service → repository → platform channel).

Findings

• high Diff truncated; full changes could not be reviewed. Evidence: pr-policy-preflight.json: diff_truncated=true, diff_bytes=462361, pr-diff.patch 截断于 app_database.g.dart 生成代码中间, 31 个变更文件中 l10n 生成文件、UI widget、部分 test 文件的变更未完整展示.
  Recommendation: Human reviewers should focus on truncated portions: app_localizations.dart/en/zh generated files, agent_activity_widget.dart UI changes, and whether all new/modified test file contents are complete.
• warn Android notification taskSummaryFromCounts uses hardcoded English. Evidence: AgentBackgroundService.kt:208-210: taskSummaryFromCounts returns "Running $processing, Pending $pending, Retry $retrying", iOS subtitle() 通过 statusText 传入已本地化文本，但 Android fallback 未走同样路径.
  Recommendation: Pass the already-localized taskSummary from Flutter rather than formatting in native Android. The PR already transmits statusText for localized text, but the fallback path still uses hardcoded English.
• warn Inconsistent _isDatabaseLocked detection patterns across files. Evidence: agent_activity_service.dart: 检测 'database is locked', 'sqliteexception(5)', 'database_busy', local_task_executor.dart: 检测 'database is locked', 'sqliteexception(5)', 'database_busy', agent_queue_background_worker.dart: 检测 'database is locked', 'sqliteexception(5)', 'code 5'.
  Recommendation: Extract _isDatabaseLocked into a shared utility function with a unified detection pattern. Currently three files implement it independently with slight variations ('database_busy' vs 'code 5'), which may cause some SQLite lock scenarios to be missed on certain paths.
• warn _localizeKnownStatusText relies on hardcoded English matching, fragile approach. Evidence: agent_background_status.dart: _localizeKnownStatusText 使用 switch 匹配 'Idle', 'Processing', 'Queued' 等英文字符串, 新增 stage 或变更 stage 文案时需要同步更新此映射.
  Recommendation: Consider using enum keys instead of English strings as internal stage identifiers, mapping to localized text only at display time. Current implementation works but has higher maintenance cost.
• info submitInput directly instantiates WorkmanagerAgentQueueDrainScheduler. Evidence: submit_input.dart: WorkmanagerAgentQueueDrainScheduler().schedule(expedited: true), AGENTS.md 规定: dependencies.dart 只注册 repository/service，通过 MemexRouter 访问.
  Recommendation: Current implementation is acceptable (scheduler is a lightweight stateless utility), but if future mocking or scheduling strategy replacement is needed, consider dependency injection.

Test Gaps

• lib/data/services/agent_run_service.dart AgentRunService is a new 508-line service. PR claims agent_run_service_test.dart (209 lines) exists, but diff truncation prevents verifying whether test coverage is sufficient (e.g., markActiveRunsPausedBySystem, resumePausedRunIfNeeded, _refreshRunFromTasks edge cases).. Suggested check: Review test/data/services/agent_run_service_test.dart for coverage of all public methods and state transitions..
• lib/ui/agent_activity/widgets/agent_activity_widget.dart agent_activity_widget.dart has +64/-9 line changes. PR claims widget test updates exist, but diff truncation prevents verifying whether UI rendering tests cover the new progress display logic (progressCompleted/progressTotal display, paused state rendering).. Suggested check: Review test/ui/agent_activity/agent_activity_widget_test.dart for paused state and progress bar rendering assertions..
• lib/db/app_database.dart (schema 14→15 migration) PR claims app_database_migration_test.dart (139 lines) validates schema migration, but diff truncation prevents confirming whether tests cover: existing data compatibility with NULL run_id after migration, and upgrade path from schema 13 or earlier directly to 15.. Suggested check: Review test/db/app_database_migration_test.dart for multi-version upgrade paths and NULL run_id data integrity..

AI review is advisory. Maintainers should verify the result before merging.

[github-actions]

PR Preflight Summary / PR 预检汇总

中文

• 统一结论：高风险：质量预检通过，但需要 maintainer 人工 review 后手动合并。
• Policy preflight：高风险。命中 1 条高风险规则，需要 maintainer 人工确认。
• Flutter quality：通过。Analyzer 和 test baseline 均未发现新增问题。
• PR head：9f9abe7a68e719884441dd8129f2687ffbe94f8c
• Policy run：27433191648
• Flutter run：27433191578

English

• Combined result: High risk: quality passed, but maintainer review is required before manual merge.
• Policy preflight: HIGH RISK. Found 1 high-risk policy signal(s); maintainer review is required.
• Flutter quality: PASS. Analyzer and test baselines found no newly introduced issue.
• PR head: 9f9abe7a68e719884441dd8129f2687ffbe94f8c
• Policy run: 27433191648
• Flutter run: 27433191578

PR Policy Preflight / PR 规则预检

PR Policy Preflight / PR 规则预检

中文

• 判定：高风险
• 变更文件数：31
• 变更行数：4487
• Diff 是否截断：true

规则命中

• 高风险 diff-truncated: Diff 超过配置的 preflight 大小限制，已被截断。

English

• Decision: HIGH RISK
• Changed files: 31
• Changed lines: 4487
• Diff truncated: true

Findings

• high diff-truncated: Diff exceeded the configured preflight size limit and was truncated.

PR Flutter Quality / Flutter 质量预检

PR Flutter Quality / Flutter 质量预检

中文

• 总体：通过
• Analyzer baseline：通过
• Test baseline：通过

English

• Overall: PASS
• Analyzer baseline: PASS
• Test baseline: PASS

Flutter Analyzer Baseline

• Base issues: 287
• PR issues: 287
• New issues: 0

No new analyzer issues introduced by this PR.

Flutter Test Baseline

• Base failures: 0
• PR failures: 0
• New failures: 0

No new Flutter test failures introduced by this PR.