Orchestrate bug sessions from the extension: amicode.reportBug command, context envelope, lifecycle handler

[jeonghun-jj-lee]

Orchestrate bug sessions from the extension: amicode.reportBug command, context envelope, lifecycle handler

Important

Problem

Someone must create and arm the bug session, hand it its context envelope, and own the machine-managed lifecycle (parent #249) — and that someone is the extension, which already holds the server port and password.

Approach

Register the amicode.reportBug command: create the session (title "Bug report", metadata bug_report: {project, run_pointer?, origin_session_id}), post the report-a-bug slash command, then send open-bug-report {sessionID} down the bridge. Add the four new message kinds to the bridge allowlist. The lifecycle handler: bug-filed → archive the session and close the dock; bug-report-closed before filing → abort the in-flight turn, then hard-delete; orchestration failure → delete the partial session (no orphans); unknown session ids ignored. Single-open invariant per window. The amicode_bug_report=1 boot param is set only when the staged skill set includes report-a-bug.

Approaches Considered

• App-side session creation — the kill-on-close owner must hold the session id, so the extension creates it; rejected.
• SSE-based filed detection — see the parent; rejected for the sentinel + bridge path.

Scope

• In: the command; the allowlist additions; create / arm / envelope; the open message; the lifecycle handler; the single-open invariant; the boot-param gate.
• Out: fork UI (slices 2–3); skill changes (slice 1); the bundle release (slice 5).

---

Acceptance Criteria

1. Invoking the command creates exactly one session with the title and metadata envelope, posts the slash command, and sends one open-bug-report with the new id; an active run controls run_pointer inclusion — pointer form only, never an absolute path.
2. bug-filed for the known id archives the session and tells the app to close the dock; bug-report-closed before any filing aborts, then deletes, the session.
3. A second invocation while a bug session is open reveals/re-expands instead of creating — never two bug sessions.
4. Creation or arming failure deletes the partial session and surfaces an error notification; bridge messages for unknown ids are dropped.
5. The boot param is present if and only if the staged skills include report-a-bug — both cases tested.
6. The originating session is never modified, navigated, or closed on any path.

Key Decisions

• The extension owns the bug session's id end-to-end — no reverse lookup, no app-reported ids.
• Archive is the soft hide (restorable); hard delete is reserved for pre-file abandonment.

Constraints & Invariants

• The bridge allowlist stays the only app→extension lane; the four new kinds are added to it, nothing else.
• No proprietary payloads in session metadata — run context travels as pointers only.

Testing Decisions

• Vitest over orchestration and lifecycle with the server API mocked at the fetch seam — each acceptance criterion maps to a test. Extends the existing chat-bridge test surface for the allowlist additions. Cross-slice edges (slice 1's sentinel contract, slice 3's dock messages) are exercised through mocked bridge traffic.

Prior Art / Patterns

• The session command API idiom (create + slash-command) and the extension's authenticated server calls (the SSE client's auth-header precedent).
• The chat bridge's strict allowlist posture.
• Session archive (soft-hide) and hard delete (permanent, recursive) — the two lifecycle endpoints.

Source

• Part of PRD: Add a Report-a-Bug entry point with machine-managed bug sessions #249 · durable record: amicode repo ADR docs/adr/0004-bug-session-lifecycle.md.

[jeonghun-jj-lee]

Slice green and merged into the unit integration branch amico/issue-249-bug-report. Integration suite on the merged branch: pnpm -r typecheck clean; pnpm -r test green (extension 872 passed / 8 skipped, schema + amico-run green). Contract notes for the record: DOWN open-bug-report/close-bug-report, UP bug-filed/bug-report-closed; origin_session_id is derived best-effort (most-recently-updated non-bug root session) since the fork button posts no origin id. Tracked by the draft PR in this repo; parent #249. (Closed by the develop DAG walk checkpoint.)