sdlc-hub/openspec/changes/archive/2026-10-13-bridge-reliability/proposal.md

Why

Мост работает в ежедневном режиме с 13.10.2026 (агент на виртуалке за VPN «Континент», обмен через общую папку UTM). Отложенные находки bridge-core (#1) и folder-transport (#5) содержат несколько мест, где живая работа может привести к дублю задачи в Jira, к команде, зависшей в claimed без пути восстановления, или к лишним запросам к Jira банка:

• M-2 — ответ на claim потерян (сбой папки, перезапуск агента во время долгого запроса): команда навсегда claimed, в журнале агента её нет; очередь стоит 10 минут, затем команда требует force-cancel или повтора.
• R-11 / O-9 — потерянный отчёт ensure_issue не закрывается подтверждением по состоянию (хаб не знает логин Jira агента); каждый такой случай требует ручного действия.
• M-5 — поздний отчёт по force-отменённой ensure_issue теряет ключ созданной задачи.
• M-11 — отчёт по команде в queued принимается; две ensure_issue с одной темой в пакете дают одну задачу на два временных ключа.
• O-3 — связь симметричного типа («Связанные»), стоящая в Jira в обратную сторону, попадает в missing_links отчёта импорта (13.10.2026 — 3 ложные тревоги).
• M-9 / O-2 — после перезапуска агент забывает время последнего вызова Jira и сразу выполняет команду без паузы темпа; при восстановлении по журналу пауза обнуляется явно.
• FM-4 — восстановление по журналу повторно пишет claimed.
• Расхождение со спекой: agent_status отдаёт признак online, спека говорит offline.

Решения владельца 13.10.2026 (сессия brainstorming):

• пакет A follow-ups — первым;
• M-2, вариант A: хаб довыдаёт команду, выданную агенту и оставшуюся без отчёта (принцип «хаб не повторяет команды» уточняется: новых команд хаб не создаёт, довыдача неподтверждённой выдачи — доставка, не повтор);
• после написания спеки, при планировании: довыдача закрывает и сценарий R-11 (потерянная ensure_issue выдаётся снова, агент находит свою задачу по reporter = currentUser()), а подтверждение по состоянию при довыдаче почти недостижимо (refresh не выдаётся, пока есть claimed). Поэтому передача логина агента и симметричных типов связей в claim из change убрана; R-11 закрывается довыдачей; O-3 — отдельным списком связей «в обратную сторону» в отчёте импорта.

What Changes

• jira-hub:
  • повторная выдача: claim при наличии команды в claimed выдаёт её снова (самую старую), счётчик deliveries; после 3 выдач без отчёта — failed «агент не отчитался после 3 выдач»; логика «свежей claimed» (10 минут простоя) и обход пакета с зависшим определителем (R-13) удаляются;
  • миграция схемы v1 → v2 (command.deliveries) с копией базы перед ней — первая миграция живой базы;
  • отчёт по queued — 409; пакет с двумя ensure_issue одной темы — 422;
  • поздний отчёт по отменённой ensure_issue с ключом сохраняет результат и переносит заметку new:N → ключ, статус остаётся cancelled;
  • отчёт импорта: связи из links.csv, которые в зеркале есть того же типа в обратную сторону, — в reversed_links, а не в missing_links;
  • заготовка настройки reporter удаляется; agent_status — redelivered вместо stuck; MCP показывает довыданные команды; принцип повторов уточняется в CLAUDE.md, ARCHITECTURE.md, docstring queue.
• jira-agent (версия 3):
  • время последнего вызова Jira восстанавливается при старте из журнала; при восстановлении пауза команды не обнуляется;
  • при восстановлении claimed повторно не пишется.
• Спеки: hub-api, data-model, commands, agent, mcp, migration — MODIFIED; признак online закрепляется в спеке вместо offline.

Non-goals

• Передача логина Jira агента и симметричных типов связей в хаб (см. Why).
• Остальные находки follow-ups (T-n, M-n вне перечня, расхождения второго порядка) — пакеты C и D.
• Проверки поведения на реальной Jira банка (CRLF, Epic Link, постраничность комментариев, поле спринта) — пакет B.
• Подъём min_agent_version до 3: агент v2 продолжает работать.
• Дубли ensure_issue между разными пакетами: поиск дубля по теме за 7 дней уже сводит их к одной задаче.

Impact

• jira-hub: queue.py (claim, report_result, agent_view, maybe_auto_refresh, reconcile), commands.py (validate, check_confirmed), importer.py, db.py (миграция v2), api.py (409 на отчёт по queued), mcp_server.py; CLAUDE.md, ARCHITECTURE.md.
• jira-agent: src/agent.py (Runner, recover, execute), README.md, версия 3.
• Контракт хаб ↔ агент: тела запросов не меняются; новый ответ 409 на отчёт по queued (агент уже трактует 409 как «закрыто»).
• Issues: aep/jira-hub#9, aep/jira-agent#9.