codex-app-server/verification/resident-p0-fixes-summary.md

常驻监听 P0+P1 修复批验证摘要（本地实现与测试，未 push、未开 PR、未合并、未部署）

• 起点：feat-resident-p0-fixes，从 origin/main 60997b1（PR #275 合并头）起； 本批只改本 worktree，绝不动生产审核 worktree、闭环 worktree、主 checkout。
• 审核依据：生产审核报告 ~/workspace/codex-app-server-resident-prod-audit/verification/resident-prod-audit-summary.md 第 4、5、7 节（动手前已重读）；范围只限该报告的 P0 与 P1。
• 不做事项：控制台 UI、选择器/区域提取、其它探针 （server_status/agent_status/relay_cost）、磁盘清理、真实外网抓取 （真实抓取只用本地测试 HTTP 服务验证）、生产 PG、生产双 worker、 真实外网只读演练（仍是需用户拍板的后续窗口，见 blocker）。
• 红线：以下所有数值凡标“拟定默认值”者，均为本批实现工拟定的 默认值、供最终验收改，不是用户已拍板；摘要、代码注释与后续 PR 描述素材里一律按此口径写，不得写成用户已定。

1. 拟定默认值清单（逐项标拟定，环境变量可覆盖）

口径	拟定默认值	环境变量	说明
每监听每日变化任务上限	24 个	CODEX_RESIDENT_MAX_DAILY_CHANGE_TASKS	按 UTC 日切分；只数 status='changed' 且 task_id 非空的轮询行；超限记 changed_capped，游标不推进
变化抖动冷却	300 秒	CODEX_RESIDENT_CHANGE_COOLDOWN_SECONDS	上次建任务 300 秒内的新变化记 changed_cooldown，游标不推进，冷却过后复查仍可报
resident_polls 保留期	90 天	CODEX_RESIDENT_POLL_RETENTION_DAYS	批量驱动每批开头 prune 一次；过期删、未过期保留；当日上限计数不受影响（保留期远大于 1 天）
批量总预算	120 秒	CODEX_RESIDENT_BATCH_BUDGET_SECONDS	单批最坏 = 预算 + 单条超时上限 60 秒；超预算的剩余监听保持 due，下批再跑
代理模式	直连（默认）	CODEX_RESIDENT_PROXY	未设/空/direct = 直连，不跟随进程代理；env = 显式跟随进程环境代理；其它值 = 显式代理 URL；两种代理模式都认进程 no_proxy/NO_PROXY
重定向上限	10 跳	（固定值）	超过抛 redirect 结构化失败

其它沿用旧值不变：间隔下限 60 秒、抓取超时 1–60 秒（默认 10 秒）、 1MB 截断、变化摘录 2000 字、poll detail 500 字、批量单批上限 50 条。

2. P0 修复与测试证据

S1. DNS 级 SSRF + 摘录口径（cloud/resident.py）

• 抓取前解析全部 A/AAAA（resolve_public_addresses）：任一地址命中 私有/回环/链路本地/保留/组播/未指定即整批拒绝；IPv6 的 IPv4 映射 地址（::ffff:127.0.0.1）按映射后 IPv4 再判；解析失败/空结果/ 非 IP 结果按 dns 失败，不放行。
• 直连建连 pin 住解析结果（_PinnedHTTPConnection / _PinnedHTTPSConnection）：TCP 对端就是解析时刻的 IP，不再二次 按主机名解析；https 的 SNI 与证书主机名仍是原始主机名（单测断言 wrap_socket(server_hostname='example.com') 且建连地址为 pin 的 IP）， TLS 校验不被 pin 破坏。
• 重定向每跳重复字面校验 + 解析门 + pin（相对跳转先 urljoin）； 非 200 一律抛 HttpStatusFetchError，错误页正文直接丢弃。
• 摘录口径（拟定）：摘录只来自已通过校验的公开抓取结果；私网 抓取在抓取层直接失败（ssrf_blocked）、不产生摘录、不建任务、 轮询 detail 只含 reason=ssrf_blocked; … 异常文本，绝不含抓取正文。 创建监听时仍只做字面校验（DNS 会变，创建时放行不等于抓取时放行）， 权威关口在抓取层——见代码注释。
• 残留风险（诚实写明，不假装已封口）：
  • 代理模式下客户端解析门只是前置检查，真正建连的是代理方、由 代理方二次解析；pin 在代理模式下不生效，须靠代理自身的 egress allowlist 兜底。生产部署若用代理模式，必须同时给代理配内网拦截。
  • 直连 pin 已把解析-建连 TOCTOU 关到“解析结果本身”这一层，但 “解析时刻的 IP 在之后被重新分配给内网用途”的极端情形不在 本次封口承诺内。
  • 旧 urllib 默认跟随进程代理的行为已改：默认直连。部署时若宿主 出口必须走代理，须显式配 CODEX_RESIDENT_PROXY=env 或代理 URL， 否则公网抓取会直连失败（记失败轮询，不建任务）。
• 测试：test_resolve_public_rejects_private_and_mixed（私网/混合/ 映射地址/解析失败）、test_ssrf_blocked_poll_has_no_excerpt_and_no_task、 test_pinned_https_uses_hostname_for_sni_not_ip、 旧重定向测试改写（默认解析器 + getaddrinfo 补丁必拦；注入 resolver 返回公网测试 IP + socket 层重定向到本地服务时相对跳转走通）。

S2. 驱动与延迟：选批量总预算，不新增独立驱动进程

• 论证：独立驱动进程的运维成本（新 unit、独立 DB 连接、启停监管） 是审核第 7 节留给用户拍板的项，本批不擅自新增；批量总预算是纯 代码改动、本地可测，且 claim 门已保证未来加驱动时多驱动不重复 轮询。预算把旧最坏 50×60=3000 秒 bound 到“预算 120 秒 + 单条 超时上限 60 秒”，剩余到期监听保持 due、下批再跑，不丢。
• 间隔只是下限、不是 SLA：resident_metrics 的 due_count / max_overdue_seconds 直接度量“到期未跑”积压，进 /metrics； 任何对外口径仍须写“尽力而为、延迟无界”（模型任务一轮最长 1800 秒仍会拖后轮询，预算只 bound 单批，不承诺送达时限）。
• 测试：test_batch_budget_stops_batch_and_keeps_rest_due （单调时钟注入：50 秒/条、预算 100 秒时跑 2 条即停，剩余 3 条仍 due）。

G2. 成本上限与保留期

• 每日上限、抖动冷却、保留期见第 1 节清单；三者均持久化 （上限数当日轮询行、冷却用既有 last_change_at、保留期靠 prune_old_polls 的 DELETE），重启不丢计数。
• 页面每轮都变时：冷却期内只记 changed_cooldown、上限满后只记 changed_capped，游标不推进（变化不丢，冷却过后/次日仍可报）， 任务数有界。
• 测试：test_daily_cap_and_cooldown_suppress_without_losing_change （上限 2、冷却 300 秒的加速版：建任务→冷却抑制→冷却后建任务→ 上限抑制，游标始终指向最后一次真实建任务的内容）、 test_prune_old_polls_keeps_recent（100 天前行删、当前行保留）。

3. P1 修复与测试证据

S3. resident 表进 PG schema 与迁移清单

• cloud/db.py 的 POSTGRES_SCHEMA 新增 resident_watches / resident_polls（含 failure_reason 列）与三条索引（含部分唯一索引 WHERE status != 'ended'）；cloud/migrations.py 的 MIGRATION_TABLES 同步新增两表（TEXT 主键，无身份列，无需序列拨动）。
• 测试：test_migration_coverage_includes_resident_tables （migration_coverage()["missing_from_migration"] == ()）； 本地 PG 实测见第 5 节。

G1. ensure 移出热路径 + 批量逐条隔离 + 死锁重试一次

• 热路径（due_watches / claim_due_watch / run_due / 批量循环）不再调 ensure_resident_tables；建表只在 server init_db（SQLite 分支新增 _res_ensure，PG 分支走 schema）、 worker 生命周期首次批量、API 函数（create/list/get/update/ transition）做。热路径只在表确实缺失时 ensure 后重试一次。
• 批量入口逐条隔离：锁错误（PG locked=True、SQLite database is locked）回滚后重试一次，仍失败记入 errors 列表并继续下一条；非锁异常同样隔离；预算耗尽信号以 watch_id=None 的条目记入 errors，供 worker 记日志。
• 测试：test_batch_isolates_item_errors_and_retries_deadlock （死锁始终失败时只影响本条、其余照常；第一次死锁第二次成功时 errors 为空）、test_hot_path_batch_executes_no_ddl （计数连接断言批量内零 CREATE 语句）。

G3. 改目标 URL 强制走一次 baseline

• update_watch 改 target_url 时 last_content_hash 置 NULL， 下一轮只建基线、不建任务；改间隔/提示/名字不重置游标， 已排好的 next_poll_at 不变（语义保留，见代码注释）。
• 测试：test_update_target_resets_baseline_but_interval_does_not。

G4. 显式代理配置 + 结构化失败原因

• 代理口径见第 1 节清单与 resident_config() 注释；默认直连 与环境变量的关系写在代码与本摘要里，不只靠隐式进程环境。
• 失败原因进 resident_polls.failure_reason 列（ensure 与 PG schema 同步补列），detail 前缀同样写 reason=<原因>； 原因集：dns / proxy / timeout / http_status / ssrf_blocked / tls / redirect / network / invalid_url / unknown。
• 测试：test_proxy_config_defaults_direct_and_env_opt_in、 test_classify_fetch_errors、test_http_status_fetch_raises_structured_error （单跳层真实 404 + default_fetch 状态分支）。

G5. resident 指标进 /metrics

• GET /metrics 新增 resident 段（成员项目过滤，与任务计数 同款）：watches_by_status、due_count、max_overdue_seconds、 近 24h polls_last_24h / failed_last_24h / changed_last_24h / change_tasks_last_24h、当前拟定 config；表缺失时 {"available": False}，不炸 /metrics。
• 测试：test_resident_metrics_counts（含到期积压与非成员过滤）、 test_metrics_contains_resident_section（HTTP 层）。

P2 建议项（顺手修，不改语义）

• resident 四个 handler 的 502 统一为固定错误码 resident_operation_failed，详情只记服务端日志（_server_log）， 不再透传可能含表名/列名的异常文本；测试 test_resident_502_uses_fixed_error_code（响应不含注入的细节串）。
• _resident_get 的 polls 异常记服务端日志（_server_log.warning）， 响应仍保持 polls=[] + polls_note="polls unavailable" 的兼容形态； 测试 test_resident_get_polls_failure_keeps_note。
• 未做（列为后续，不硬修）：改间隔立即生效的语义（仍为“暂停后 恢复才立即复查”，已写进注释与本摘要）；选择器/区域提取； 控制台 UI。

4. 测试结果

• 定向（最后一次纯文案修订后重跑，见时间关系说明）： python3 -m unittest cloud.tests.test_resident cloud.tests.test_resident_server cloud.tests.test_resident_website_loop cloud.tests.test_resident_p0_fixes —— 38 项全过（旧 20 项 + 新 18 项）。
• ruff E,F（被碰文件）：与改动前基线一致的 12 项，全是旧代码 （含 cloud/worker.py 的 F821、cloud/server.py 旧中文注释超长行等）， 本批新增 0 项（新增的 3 项在自查中已修掉）。
• CI 同款三条 discover 全量（均在本批代码定稿后跑出）：
  • python3 -m unittest discover -s cloud/tests：1569 项，OK（跳过 9 项），393 秒；
  • python3 -m unittest discover -s deploy/tests：44 项，OK，12 秒 （尾部三行中文传输日志为某测试退出时打印，不影响结果）；
  • python3 -m unittest discover -s tests：105 项，OK，12 秒。
• 时间关系：定向 38 项先于全量跑出；全量三条跑完后，本摘要 填入全量数字（纯文案修订，不碰代码与测试），随后按任务要求 重跑定向——重跑结果仍为 38 项全过，与全量结论一致；摘要定稿 在定向重跑之后，不再有代码或测试改动。

5. 本地 PG 16 验证单独记录（一次性库，测完已删库删脚本）

• 方式：initdb --auth=trust 一次性库（Unix socket，psycopg2 适配层），脚本放 /tmp（不进 worktree），测完停库、删库、 删脚本；结论只代表本地 PG，不代表生产 PG。
• 结果（全部通过）：
  • init_postgres_schema 后 resident_watches / resident_polls 齐全；
  • 索引在位：idx_resident_watches_project、 idx_resident_watches_name（部分唯一， WHERE (status <> 'ended'::text)）、idx_resident_polls_watch；
  • 二次 init_postgres_schema + ensure_resident_tables 幂等；
  • migration_coverage 无缺失；SQLite→PG 迁移 resident 两表各 1 行；
  • 基线→变化→queued 任务、已结束名重用全部通过；
  • 双连接并发：胜者 1 条 baseline 轮询、败者 0 条且 errors 为空、 全程无死锁异常、无整批 abort、poll 总数 1（G1 修复后败者干净返回； 旧死锁形态未再出现，但“双连接”不等于“生产双 worker”，见偏差）。
• 已清理：集群目录、socket 目录、日志与 /tmp 脚本均已删除， ls /tmp/resident_pg* 确认无残留。

6. 已知偏差

• 本地 PG 结论不是生产 PG 结论；本地 HTTP 结论不是真实外网结论； 双连接结论不是生产双 worker 结论；真实外网只读抓取演练仍未做。
• 代理模式下 pin 不生效（见 S1 残留风险），须靠代理 egress allowlist。
• 旧闭环测试第 5 步轮询时刻由 t0+400 改为 t0+540：新冷却语义下 160 秒间隔的变化会被正确抑制，测试改按冷却期外复查（注释已写明）， 不是为通过而删断言。
• 旧重定向测试与闭环测试的本地服务接法改为“resolver 返回公网测试 IP + socket 层重定向”：门与 pin 全程真实跑，只有传输层终点是 测试替身；门本身由默认解析器用例独立覆盖。
• resident_config() 每次调用读环境变量：改环境变量即生效， 但已启动进程的既有默认值不会跨进程同步（与其它环境变量配置同款）。
• 无效环境变量数值（非整数/<=0）回落默认值，不炸驱动（配置错误 按默认跑，运维侧须自行核对配置是否生效，见 /metrics 的 config 段）。

7. blocker（需用户拍板，本批不擅自定）

• 拟定默认值清单（第 1 节全部）：上限 24、冷却 300 秒、保留期 90 天、 批量预算 120 秒、默认直连代理——供最终验收改。
• 是否新增独立驱动进程（本批选批量总预算，见 S2 论证；独立驱动 仍是可选项，需用户定运维成本）。
• SSRF 修复后的摘录口径最终版：本批拟定为“只来自已通过校验的 公开抓取结果”；是否进一步收紧为只留 hash/长度/脱敏摘录，仍由 用户定。
• 生产 PG 双 worker 实测窗口、真实外网只读抓取演练窗口、 代理模式下的代理 egress allowlist 配置（若生产用代理模式）。
• 控制台 UI 是否随修复批上（属产品范围，不计入本轮）。

8. 未做事项（本批明确不做）

• 未 push、未开 PR、未合并、未部署；工作区未提交（由 parent 定）。
• 未碰生产审核 worktree、闭环 worktree、主 checkout（feat-repo-picker）。
• 未做控制台 UI、选择器/区域提取、其它探针、磁盘清理、真实外网抓取。
• 未改生产默认值以外的任何行为口径；旧测试除上述两处时序/接法 调整外无删断言、无加 skip。