Sync Phase 6 follow-up queue and dirty handoff

[StatPan]

Goal

Sync the Phase 6 follow-up state, explain the current dirty branch handoff, and define the next production milestone boundary without starting new implementation.

Context

Workspace sync found Agentree active after Phase 6. Local branch fix/phase6-review-followup contains broad dirty changes across UI panel behavior, server routes, OpenCode compatibility, approval handling, SSE, CI/security dependency checks, and AGENTS guidance.

This issue is a PM/triage handoff, not a coding task.

Scope

• Review Phase 6 follow-up state and current branch status.
• Explain the dirty worktree by functional area and risk level.
• Decide whether the current dirty branch should become one PR or be split into follow-up issues.
• Identify which changes are UI-visible and therefore require owner review.
• Create or recommend concrete follow-up issues for the next production milestone after Phase 6.

Out of Scope

• Do not implement new code from this issue.
• Do not rewrite the dirty worktree.
• Do not revert existing changes.
• Do not create final UI decisions without owner review.

Acceptance Criteria

Functional:

• Dirty state is explained by changed-file bucket and intended behavior.
• Current branch handoff is summarized with likely PR/split recommendation.
• Next milestone boundary is written as GitHub issues or explicitly deferred.

Code/product quality:

• Risks and missing tests are identified.
• UI-visible behavior changes are marked for owner review.
• Server/API/approval/SSE compatibility risks are separated from UI polish risks.

Operational:

• No code implementation is started from this issue.
• Existing user/worker changes are preserved.

Expected Delivery

• Delivery mode: planner/triage report first.
• Review mode: control plane reviews the report and decides whether to create follow-up issues or request owner review.
• Merge mode: no merge from this issue unless a later PR is explicitly created for the dirty handoff.

Doctor Impact

No Gira doctor, audit, status, finish, branch policy, provider, or workflow-report behavior changes are expected. This is Agentree PM/triage work only.

[StatPan]

Handoff

Planner handoff: Phase 6 dirty branch and next milestone boundary

Current state

• Active local branch inspected: fix/phase6-review-followup, tracking origin/fix/phase6-review-followup.
• Linked open PR on that branch: fix: Phase 6 review follow-up — shared util, GET side-effect, dead branch, test gap #13, fix: Phase 6 review follow-up — shared util, GET side-effect, dead branch, test gap.
• PR fix: Phase 6 review follow-up — shared util, GET side-effect, dead branch, test gap #13 committed scope is narrow and mergeable, with prior CI success on 2026-04-19. It includes projectGroupFromDirectory, removal of the GET /api/agent/tree DB side effect, one canvas style cleanup, and an agent route test gap.
• The current local worktree has broad uncommitted changes on top of PR fix: Phase 6 review follow-up — shared util, GET side-effect, dead branch, test gap #13. They are not described by PR fix: Phase 6 review follow-up — shared util, GET side-effect, dead branch, test gap #13 and should not be pushed to that PR as-is.
• Gira Sync Phase 6 follow-up queue and dirty handoff #14 lifecycle start was dry-run only. I did not apply it because applying would create/switch to issue-14-sync-phase-6-follow-up-queue-and-dirty-handoff, which risks disturbing the dirty branch this ticket is meant to preserve and explain.
• No code implementation, rewrite, revert, or formatting edit was performed.

Dirty changed-file buckets

1. Approval/question UX and local state, high product risk, UI-visible and owner-review required

   • Files: src/client/panel/ApprovalQueue.tsx, src/client/panel/SessionPanel.tsx, src/client/store/agentStore.ts.
   • Intended behavior: hide the selected session from the global approval queue, support choice-style questions, allow single/multiple option selection, clear pending permissions/questions after reply/reject, and synthesize local question replies into the message list.
   • Risk: visible workflow changes for approval handling and message history. The local synthetic reply path may diverge from OpenCode truth if the backend rejects, delays, or later reports a different persisted message shape. Current client typecheck fails in this area.

2. Server pending-state/API compatibility, high integration risk

   • Files: src/server/routes/agent.ts, src/server/routes/tree.ts, src/server/opencode/adapters/compat-1.3.ts, src/server/opencode/client.ts, src/server/opencode/types.ts.
   • Intended behavior: fetch pending permissions/questions directly from OpenCode REST endpoints, merge pending state into tree responses, expose auth/base URL for raw REST fallbacks, and reply to questions using a raw /question/:requestID/reply request.
   • Risk: changes the server/OpenCode compatibility contract and fallback behavior. It moves pending-state source from SSE broadcaster memory toward direct adapter calls in tree routes. Existing route tests were not updated and currently fail.

3. Approval route and SSE cleanup, medium/high compatibility risk

   • Files: src/server/routes/approval.ts, src/server/sse/broadcaster.ts, src/server/routes/approval.test.ts.
   • Intended behavior: normalize answer payloads without requiring question IDs, resolve local pending question state after reply, and broadcast a synthetic question.replied event.
   • Risk: answer payload shape changes from { questionID, value } toward string arrays. That needs validation against OpenCode 1.3 behavior and browser/SSE ordering. It also only resolves questions, not permissions, via the broadcaster path.

4. Server config polish, low/medium operational risk

   • File: src/server/index.ts.
   • Intended behavior: honor PORT instead of hardcoding 3001.
   • Risk: low, but should be tested with dev/proxy docs and Docker/compose expectations.

5. Security/dependency CI gate, medium release/process risk

   • Files: .github/workflows/ci.yml, package.json, pnpm-lock.yaml, scripts/check-security-deps.mjs.
   • Intended behavior: add a local dependency security floor check, run it in CI and prebuild, and bump React/React DOM from 19.2.4 to 19.2.6.
   • Risk: this is a policy/release gate, not a Phase 6 runtime fix. It can block builds for unrelated dependency ranges and should be reviewed separately from approval/SSE work.

6. Project guidance cleanup, low runtime risk but high handoff visibility

   • File: AGENTS.md.
   • Intended behavior: replace the old long Codex handoff with the concise current project entry point.
   • Risk: no runtime risk, but it removes historical operational detail from the active prompt file. This is acceptable only if CLAUDE.md/docs remain the historical reference.

PR/split recommendation

Do not make the current dirty branch one PR. Keep PR #13 narrow or refresh it only with fixes directly tied to its existing review-follow-up scope. Split the uncommitted patch into separate follow-up issues/PRs because it mixes UI-visible approval behavior, OpenCode API/SSE compatibility, CI security policy, server config, and project guidance.

Recommended sequence:

1. Finish/review PR fix: Phase 6 review follow-up — shared util, GET side-effect, dead branch, test gap #13 independently if still wanted. Do not append the broad dirty worktree to it.
2. Stabilize approval/question server compatibility before UI polish. The UI relies on the API/SSE contract being correct.
3. Run owner review on all approval/question UI behavior before merge.
4. Keep dependency security policy and AGENTS cleanup as separate low-blast-radius PRs.
5. Continue the Gira work-map roadmap after Phase 6 stabilization. Existing milestone issues are [Epic] Gira-based agent work map roadmap #15 epic, Design Agentree work-node schema and Gira identity mapping #17 schema/design, Prototype Gira/GitHub read model for ticket, branch, PR, and checks #16 read model, and Add read-only Gira work-map import from workspace status JSON #18 import path; Add read-only Gira work-map import from workspace status JSON #18 already has PR Add read-only Gira work-map import #19 open with CI success and review-required state.

Proposed follow-up issues for the next production milestone

Issue A: Stabilize OpenCode pending approval/question compatibility

Goal: Make pending permission/question discovery and reply handling reliable across /api/tree, /api/agent/tree, approval routes, SSE state, and OpenCode 1.3.

Scope:

• Decide the canonical pending-state source: direct OpenCode REST, SSE broadcaster memory, or a documented merge of both.
• Validate /permission, /question, and /question/:requestID/reply request/response shapes against OpenCode 1.3.
• Update adapter interfaces and route tests together.
• Preserve read-only session state except explicit approval/question replies.

Acceptance criteria:

• GET /api/tree and GET /api/agent/tree expose pending permissions/questions consistently.
• Pending status overrides are deterministic when permission and question are both present.
• Question replies use the OpenCode-compatible payload shape and include regression tests for freeform and option answers.
• SSE cleanup after reply/reject is covered by tests or explicitly documented as eventual-consistency behavior.

Verification:

• ./node_modules/.bin/vitest run src/server/routes/agent.test.ts src/server/routes/approval.test.ts src/server/sse/broadcaster.test.ts
• ./node_modules/.bin/tsc -p tsconfig.json --noEmit
• git diff --check
• Optional/manual: run against a live OpenCode 1.3 server with one permission request and one question request.

Issue B: Owner-review approval/question panel UX

Goal: Ship the UI-visible approval queue/session panel behavior only after the owner confirms the interaction model.

Scope:

• Review whether selected-session requests should disappear from the global approval queue.
• Review choice buttons, multi-select behavior, custom-answer visibility, reject behavior, and local synthetic reply messages.
• Keep final UI behavior aligned between ApprovalQueue and SessionPanel.

Acceptance criteria:

• Owner-approved screenshots or notes exist for permission and question flows.
• No duplicate pending request appears between selected-session panel and global queue unless intentionally designed.
• Local reply display either matches persisted OpenCode messages or is clearly marked as optimistic/local and reconciled on refresh.
• Client typecheck passes.

Verification:

• ./node_modules/.bin/tsc -p tsconfig.client.json --noEmit
• ./node_modules/.bin/vitest run src/client/store/agentStore.test.ts if store behavior changes are covered, otherwise add focused store tests in that issue.
• Browser/manual check with pending permission, freeform question, single-choice question, multi-choice question, and reject paths.

Issue C: Add dependency security floor as separate CI policy

Goal: Add the dependency security gate without coupling it to approval/SSE changes.

Scope:

• Review the package/version floors and whether they belong in prebuild, CI, or both.
• Keep React/React DOM lockfile changes in this PR if still required.
• Document how to update the floor when advisory state changes.

Acceptance criteria:

• Security check passes locally and in CI.
• The policy does not recurse into irrelevant package manifests or generated/vendor directories.
• Failure messages clearly name package, location, found version, and required floor.

Verification:

• node scripts/check-security-deps.mjs
• ./node_modules/.bin/tsc -p tsconfig.json --noEmit
• CI run on PR.

Issue D: Make server port configurable

Goal: Honor PORT for the Hono server without breaking Vite proxy, Docker, or CLI expectations.

Scope:

• Keep the change to src/server/index.ts and docs/config references.
• Confirm compose/dev defaults remain 3001.

Acceptance criteria:

• Server uses PORT when set and defaults to 3001 when unset.
• README/compose/dev guidance remains accurate.

Verification:

• PORT=3002 ./node_modules/.bin/tsx src/server/index.ts smoke test if OpenCode/env is available, or a focused config/unit test if not.
• ./node_modules/.bin/tsc -p tsconfig.json --noEmit.

Issue E: Refresh AGENTS guidance after Phase 6

Goal: Keep AGENTS.md as the concise project entry point while preserving older operational context elsewhere.

Scope:

• Replace or retain the concise AGENTS.md content after owner review.
• Confirm legacy operational material remains discoverable in CLAUDE.md or docs.

Acceptance criteria:

• AGENTS.md accurately points to current execution source, spec source, and next action.
• No historical implementation details are lost without an alternate reference.

Verification:

• Documentation review only.
• git diff --check.

Existing next milestone boundary

The production milestone after Phase 6 should be split into two layers:

1. Phase 6 stabilization and approval reliability:

   • Complete or retire PR fix: Phase 6 review follow-up — shared util, GET side-effect, dead branch, test gap #13.
   • Execute Issues A and B before treating the live control UI as production-ready.
   • Keep Issues C, D, and E independent and non-blocking unless release policy requires them.

2. Gira-backed work-map roadmap:

   • Existing [Epic] Gira-based agent work map roadmap #15 is the epic.
   • Existing Design Agentree work-node schema and Gira identity mapping #17 should precede or validate Prototype Gira/GitHub read model for ticket, branch, PR, and checks #16 where schema decisions are still open.
   • Existing Add read-only Gira work-map import from workspace status JSON #18 has PR Add read-only Gira work-map import #19 open and can proceed as the read-only import path, subject to review.
   • Do not start mutating GitHub/Gira from Agentree in this milestone.

New issue creation is explicitly deferred pending owner/control-plane decision. This note provides queue-ready issue definitions if the owner wants them created.

Verification run from this handoff

• gira ticket prompt --repo StatPan/agentree --ticket 14 --role planner --json passed.
• gira ticket view --repo StatPan/agentree --ticket 14 passed and reported next step gira ticket start --apply.
• gira ticket start 14 --repo StatPan/agentree --dry-run --json passed; not applied to preserve dirty handoff state.
• gh issue list --repo StatPan/agentree --state all --limit 50 --json ... passed.
• gh pr view 13 --repo StatPan/agentree --json ... passed.
• gh pr view 19 --repo StatPan/agentree --json ... passed.
• node scripts/check-security-deps.mjs passed.
• ./node_modules/.bin/tsc --noEmit passed.
• ./node_modules/.bin/tsc -p tsconfig.client.json --noEmit failed with client question option typing errors in ApprovalQueue.tsx and SessionPanel.tsx.
• ./node_modules/.bin/vitest run src/server/routes/agent.test.ts src/server/routes/approval.test.ts src/server/sse/broadcaster.test.ts failed: agent.test.ts has 10 failures because the dirty agent.ts now calls opencodeAdapter.listPendingPermissions, but the existing test mock does not provide that method. approval.test.ts and broadcaster.test.ts passed in that run.
• git diff --check passed.

Environment caveat: pnpm is not on PATH here and corepack is also unavailable, so equivalent local checks were run with node and checked-out binaries under node_modules/.bin.

Context:

• Ticket: Sync Phase 6 follow-up queue and dirty handoff #14
• Status: Ready
• Linked PR: none
• Blockers: missing_linked_pr
• Next: gira ticket start --repo StatPan/agentree --ticket 14 --apply

[StatPan]

Handoff

Control-plane split completed

The #14 dirty-branch handoff has been converted into concrete follow-up tickets. The local fix/phase6-review-followup worktree was not modified.

Created follow-ups:

• Stabilize OpenCode pending approval/question compatibility #20 Stabilize OpenCode pending approval/question compatibility — worker-ready P1 backend/API/SSE contract task.
• Owner-review approval/question panel UX #21 Owner-review approval/question panel UX — owner-visible UI decision task, intentionally blocked pending owner review.
• Add dependency security floor as separate CI policy #22 Add dependency security floor as separate CI policy — worker-ready separate CI/security policy task.
• Make server port configurable #23 Make server port configurable — worker-ready focused server config task.
• Refresh AGENTS guidance after Phase 6 #24 Refresh AGENTS guidance after Phase 6 — worker-ready docs/handoff task.

Execution guidance:

• Start Stabilize OpenCode pending approval/question compatibility #20 before any approval/question UI merge because the panel UX depends on the API/SSE/OpenCode pending-state contract.
• Keep Owner-review approval/question panel UX #21 escalated to owner review because it changes visible approval/question behavior.
• Keep Add dependency security floor as separate CI policy #22, Make server port configurable #23, and Refresh AGENTS guidance after Phase 6 #24 as separate low-blast-radius PRs.
• Do not append the broad dirty worktree to PR fix: Phase 6 review follow-up — shared util, GET side-effect, dead branch, test gap #13.

No code edits, branch switches, or dirty-worktree rewrites were performed as part of this split.

Context:

• Ticket: Sync Phase 6 follow-up queue and dirty handoff #14
• Status: Ready
• Linked PR: none
• Blockers: missing_linked_pr
• Next: gira ticket start --repo StatPan/agentree --ticket 14 --apply

[StatPan]

Closed after splitting the Phase 6 dirty-branch handoff into #20, #21, #22, #23, and #24. No code changes were made from #14.