Staff session staffId persistence

[SuuBro]

Summary

Staff sessions silently lost their staffId association across server restart / agent CLI respawn. The three inbox tools (inbox_list, inbox_complete, inbox_dismiss) are gated by BOBBIT_STAFF_ID in the agent process env, set on every (re)spawn from PersistedSession.staffId. Pre-fix, StaffManager mutated session.staffId only in memory — SessionManager.createSession() didn't accept staffId in its opts, so plan.staffId stayed undefined and persistOnce wrote nothing to disk. On respawn, restoreSession read ps.staffId = undefined → no env var → inbox tools refused to register → staff agent could never mark entries complete, and pending entries re-fired forever.

Root cause

• StaffManager.createStaff / ensureSessionForStaff set session.staffId = id after createSession() returned — purely in memory.
• SessionManager.createSession had no staffId field in its inline opts type, so the field never reached either plan-builder.
• persistOnce() faithfully writes staffId: plan.staffId — but with plan.staffId always undefined for staff sessions, the persisted record on disk was always missing staffId.

Fix

1. Spawn-path plumbing — added staffId?: string to SessionManager.createSession opts; threaded staffId: opts?.staffId, into both plan-builder literals (worktree branch and normal branch).
2. Staff-manager call sites — pass staffId: id in both createSession invocations.
3. One-shot backfill migration — new src/server/agent/staff-backfill.ts runs at server boot, finds sessions with no staffId whose title matches a staff name AND whose worktreePath/cwd matches the staff's worktree, and heals them with a loud warn log. Conservative — refuses title-only matches.

Regression test

tests/staff-session-staffid-persistence.test.ts — 7 tests across 3 describe blocks:

• Spawn-path regression (source grep for the staffId: opts?.staffId, plan-builder lines, fails on master, passes after fix) + behavioural round-trip via persistOnce.
• Forward guard for staffId round-trip through store.put.
• Backfill migration — happy path, idempotency, conservative-match rejection (title-only without worktree agreement does NOT backfill).
• Source guards for restoreSession env wiring and persistOnce write.

All 7 pass on this branch; coder confirmed they fail on master when the source fix is stashed.

Documentation

• docs/debugging.md — new symptom entry "Staff inbox tools missing after restart / [INBOX] completion silently fails" with jq diagnostic, expected warn log, the four spawn-path wires, and a pointer to the pinning test.
• Module docstring on staff-backfill.ts and one-liner comments on the load-bearing plan-builder and call-site lines, all pointing to the regression test.

Verification

• npm run check — pass
• npm run test:unit — 1101 pass
• npm run test:e2e — 1111 pass, 11 flaky-retry passes, 8 skipped

Out of scope (deferred to follow-ups)

• Inbox-tool error UX when BOBBIT_STAFF_ID is missing (spec Enforce PR-only master policy in team-lead prompt #5). The fix means this state never happens for new sessions and the backfill heals existing ones, so the original motivation evaporated.
• Generalising the fix to BOBBIT_GOAL_ID / BOBBIT_TASK_ID — investigation shows those already work correctly via plan.goalId / plan.taskId.

🤖 Generated with Bobbit