feat(nubi): add query timeout flag, resilient polling, and recovery hints

[blue4209211]

Summary of Changes

1. Add --timeout / -t flag to nbctl nubi query

• Allows configuring maximum wait duration for queries (e.g. --timeout 5m, -t 2m).
• Defaults to 0 (unlimited / wait until complete or canceled, preserving existing behavior).

2. Fix Polling Parameter Isolation (pkg/nubi/nubi.go)

• Fixed bug where GetConversation set both conversationId and sessionId to idToUse when polling by session ID.
• In ai_get_conversation_v3, the backend filter WHERE ($3::uuid IS NULL OR c.id = $3::uuid) AND ($4::text IS NULL OR c.session_id = $4::text) caused 0 rows to match because conversation UUID never equals session UUID.
• Now isolates parameters: sends only conversationId when available, or only sessionId otherwise.

3. Add --account-id Flag to nbctl nubi get (cmd/nubi_get.go)

• Added --account-id flag to nubiGetCmd and resolved account ID via resolveAccountID(cmd) to allow overriding profile default account.
• In JSON mode (-o json), returns a non-zero error when the conversation is not found for the account rather than exiting 0 with an empty response.

4. Account Scoping in Recovery Hints

• Updated timeout and cancellation recovery hints (both text and JSON) to append --account-id <id> to suggested nbctl nubi get commands.

5. Resilient Polling & Live Progress Updates

• Performs an immediate check on start so quick investigations resolve without a 2-second wait and conversation metadata is captured immediately.
• Retries up to 5 consecutive transient network/HTTP errors instead of aborting the query while the server is actively working.
• Updates spinner suffix dynamically with statusText from GetConversation.

6. Clear Post-Timeout & Post-Cancellation Guidance

When a query times out or is canceled:

• Text Mode:
  • Displays: Query timed out after <duration>. or Request canceled.
  • Informs the user that the investigation was triggered and may still be running or completed server-side.
  • Prints the Session ID and Conversation ID (if resolved).
  • Gives the exact command to retrieve the response once completed:

    nbctl nubi get <conversation-id> --account-id <account-id>
    # or: nbctl nubi get --session-id <session-id> --account-id <account-id>

  • Provides the web console URL.
  • Explains how to increase the timeout or run asynchronously.
• JSON Mode (--format json / -o json):
  • Emits structured JSON with status, error, session ID, conversation ID, and recovery hint.

7. Machine-Readable Trigger Errors & Access Hints

• When --async -o json or synchronous -o json encounters a trigger error (such as api: user does not have access), it outputs structured JSON on stdout.
• Appends contextual diagnostic hints when account-level access is denied.

8. Test Isolation Fix in pkg/testutil/helpers.go

• Ensured RunWithMockServer sets NBCTL_TESTING=true during mock execution to prevent tests from reading ~/.nudgebee/config and connecting to production.

---

Verification

• Added TestNubiClient_GetConversation_ParameterIsolation in pkg/nubi/nubi_test.go.
• Added TestNubiCmd_Get_WithAccountId, TestNubiCmd_Get_SessionId_WithAccountId, TestNubiCmd_Get_NotFound_JSON, and TestNubiCmd_SyncQuery_SessionIdDiffersFromConversationId in cmd/nubi_test.go.
• All unit tests passing (go test -v ./...).
• Linter passing (make lint / golangci-lint run with 0 issues).

[gemini-code-assist]

Code Review

This pull request introduces a --timeout flag to the nubi query command, improves error handling for timeouts and cancellations (with detailed user guidance for both text and JSON outputs), and refactors the polling mechanism to tolerate transient errors and use a ticker. It also adds comprehensive tests for these scenarios. The review feedback suggests improving sub-second duration rounding to avoid displaying 0s and enhancing context error checks in the polling loop to ensure robust handling of cancellations and timeouts.

[blue4209211]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a '--timeout' flag to the 'nubi query' command, enhances error handling and recovery messaging for timeouts and cancellations (supporting both text and JSON outputs), and refactors the polling mechanism to use a ticker with transient error retries. The review feedback highlights several improvement opportunities, including addressing a potential data race with the spinner suffix, avoiding thread-unsafe dynamic environment variable modifications in tests, robustly distinguishing trigger errors from polling errors instead of relying on string matching, and ensuring non-zero exit codes are returned on failure in JSON mode.