# One permit selection for text and voice

The permit card's **Ask about this permit** button selects its exact Workspace permit ID. The chat state dropdown selects the latest uploaded permit for that state and shows its permit number. **Back to trip chat** / **Whole trip** clears the selection. An exact button selection is not replaced by another permit from the same state.

Text and voice use the same permit ID and state. The selected permit's text and that state's provisions/internal notes are the sources for permit-rule comparisons and confidence. Trip load dimensions, truck/trailer and pickup/delivery remain available as context. Other permits and other states' rules are excluded from tools; an unknown or foreign permit never falls back to whole-trip data.

## Backend contract

The existing authenticated endpoints accept two additional optional fields:

```json
{
  "workspace_trip_id": "immutable-workspace-trip-uuid",
  "permit_id": "exact-workspace-permit-uuid",
  "state_code": "LA"
}
```

`POST /api/workspace/logistics-chat` also receives the existing `message`, `history` and `language`. `POST /api/workspace/logistics-voice/token` also receives `browser_id`, `viewer_user_id`, `name` and `language`. Whole-trip requests omit the two selection fields.

The backend validates the ID against `all_trips.order.routeData[].workspace_permit_id` for that exact trip. Its response includes `permit_scope` with the validated trip ID, permit ID, state code/name and permit number. Scoped Workspace requests require this acknowledgement; an older backend that ignores selection cannot supply a whole-trip answer under a selected-permit label.

Voice sessions store `sessions.workspace_permit_scope`. The worker binds this context around its initial snapshot and each tool execution. Context is local to the request/job and propagates into its tool threads; it is reset after use. Simultaneous selections cannot overwrite each other. Scoped voice browser identities include the permit ID so switching permits uses a separate session record and conversation.

The worker publishes the validated selection in participant attributes `workspace.permit_id` and `workspace.state_code`. Workspace checks both before opening the microphone or accepting speech transcripts. A worker that has not been updated cannot silently use whole-trip context. Switching the selection while voice is active disconnects the old room and opens a fresh room using the new selection; late events from the old room are ignored.

Transcript saving stays independent of optional source lookup. Saved voice questions/replies carry the permit and state captured by their voice session. Source enrichment also checks the backend session's permit ID, so another selection's citations cannot be attached to a similar-sounding reply.

## Deployment required

The October 13 live investigation also found another anonymous LiveKit worker receiving Workspace rooms. The backend routing fix explicitly targets `hha-workspace-logistics-v1`. Start the dedicated Workspace worker in `LOGISTICS_AGENT_MODE=workspace` on health port 8083 before restarting Flask. The existing Synchron worker remains separate. The backend's `docs/WORKSPACE-VOICE-DISPATCH.md` contains the exact cPanel startup command and verification steps. This routing update requires no further Workspace code or SQL changes.

1. Update the **Heavy-Haul-GpT** backend checkout to include `logistics_bot/workspace_scope.py` and the changes to `routes/workspace_updates.py`, `logistics_bot/db.py`, `logistics_bot/utils/tools.py`, `logistics_bot/prompt_builder.py` and `logistics_bot/livekit_agent.py`.
2. Restart both the existing Flask API process and the existing Logistics Bot LiveKit worker. Updating the API alone does not update an already-running voice worker.
3. Deploy the Workspace commit, then refresh the trip and reconnect voice. Localhost uses the corrected Workspace code but its configured remote backend also needs steps 1–2.

No Laravel endpoint, package installation or new database migration is required for permit selection. Existing state-sync/source-evidence deployment requirements remain separate. This change does not modify the Synchron eight-digit order contract.

## Acceptance checks

- Click Louisiana **Ask about this permit**, then ask by text and voice which permit is being discussed. Only the displayed Louisiana permit may be identified.
- Choose Alabama in the dropdown while voice is active. The old room must stop and the new worker must confirm the Alabama permit before receiving microphone input. Follow-up references such as “this permit” must refer to Alabama.
- Ask a permit-rule question and expand its sources. Permit citations must reference only the selected permit; provision/notes citations must reference the same state. Missing source text is reported honestly and scores are not invented.
- With two permits in one state, click the older permit directly. Its ID must remain selected, even though the state dropdown's default chooses the latest upload.
- Clear the selection with **Whole trip** and verify multi-state questions work again. Reload and verify saved voice rows keep their original permit/state and question links.

Automated checks cover same-state permits, foreign-trip IDs, mismatched states, text/voice acknowledgements, isolated tool threads, source gathering and unchanged normal transcript saving. A read-only check of the real Louisiana trip record confirmed one selected permit plus available permit text, Louisiana provisions and Louisiana notes. Remote deployment and a live microphone conversation still require activation on the backend host.
