Crash Reporting and Feedback

Automatic crash reporting

When Polytoken exits unexpectedly, it sends a crash report to the Polytoken team. The report helps diagnose and fix the problem that caused the exit.

A crash report includes the crash type, the error message, a stack trace with file paths reduced to component names, the component that crashed, the Polytoken version, the operating-system family, the CPU architecture, and your pseudonymous installation ID.

Polytoken does not automatically attach daemon logs, session records, prompts, tool or conversation data, environment variables, breadcrumbs, or files to a crash report. Even after scrubbing, crash details may contain incidental paths or user-derived fragments that the scrubbing process cannot predict.

Default-on behavior

Automatic crash reporting is on by default once your user or global config loads successfully. If your global config is missing, unreadable, or malformed, crash reporting stays off. This fail-closed design means a broken configuration never silently sends reports.

A successfully configured headless daemon (one started by the CLI with a valid config) has crash reporting on by default. The only way to turn automatic crash reporting off is data.automatic_crash_reporting = false in your global config.

Global-only config

The data.automatic_crash_reporting key is global-only. Project configs may not set or erase it. Polytoken rejects any attempt to write this key from a project config layer.

To turn automatic crash reporting off, add the following to your global config:

[data]
automatic_crash_reporting = false

To review or change this setting interactively, open the Configurator and select the Data tab.

First-start license acceptance

On first start, Polytoken shows a blocking acceptance dialog before the session opens. The dialog states that using Polytoken implies acceptance of the end user license agreement and privacy policy, and it explains where crash diagnostics and feedback submissions go (Sentry in the United States, and Atlassian for feedback triage).

The dialog offers three choices:

• View the agreement opens the license viewer over the dialog, where you can read the license agreement, the privacy policy, and the open-source licenses. Press Escape or click outside the viewer to return to the dialog.
• Accept records your acceptance and starts the session. Polytoken saves the acceptance, so the dialog does not appear again until the documents change.
• Reject ends the session immediately and exits. The daemon session terminates and Polytoken exits with code 0.

Escape and Ctrl+C do not dismiss the dialog: an explicit choice is required. The dialog reappears whenever the license documents or its own text change materially, so you always have a chance to review updates before continuing.

Installation ID

The installation ID is a random, machine-local identifier Polytoken uses to correlate reports from the same installation. This identifier does not encode your name, email address, hostname, or account.

Data region

Submitted event data, including crash reports and feedback, is stored in the United States.

Sending feedback

Open the feedback form in either of these ways:

• Type /feedback in the prompt.
• Press Ctrl+Shift+F (feedback-open) while the conversation is focused.

The form has a text editor for your message, a list of optional attachments, and a send button. The text editor accepts up to 16 KiB of UTF-8 text. You must type a message before you can send feedback.

Before submission, Polytoken scrubs typed text for recognized secret patterns, replacing matches such as API keys, bearer tokens, and password assignments with [REDACTED]. This is best-effort handling rather than a guarantee that every sensitive value will be found.

Set POLYTOKEN_DISABLE_FEEDBACK=1 before launching Polytoken to disable manual feedback, including /feedback and Ctrl+Shift+F. Relaunch the TUI after changing the variable.

Attachments

The feedback form can offer the current TUI log as an optional attachment. Polytoken reads the most recent portion of that file when you send feedback, up to 5 MiB. If the file is larger, the attachment includes a notice that it was truncated. The size shown in the form describes the whole file; sending is evaluated using the bounded portion that will actually be attached.

The TUI-log attachment is scrubbed for recognized secret patterns using the same best-effort handling as typed feedback. Scrubbing can miss sensitive values, so review your feedback before sending. If the log is unavailable when you send, Polytoken does not submit the feedback.

You can also add up to three screenshots from the system clipboard. Screenshots are not scrubbed. Do not include secrets or other sensitive information in a screenshot.

With the form open, use the paste-image shortcut, which defaults to Ctrl+Alt+V, to add a screenshot. Use the pasted-image-remove shortcut, which defaults to Ctrl+Alt+X, to remove all screenshots from the form. You can change both shortcuts through tui.keyboard.commands.

Polytoken reduces each screenshot to a JPEG with a maximum dimension of 1600 pixels and an encoded size of at most 1 MiB. The current TUI-log tail and screenshots count toward a 20 MiB aggregate attachment limit. A large whole-file log can therefore still be sent when its bounded tail fits within the limit; adding screenshots can make the selected attachments exceed the limit.

Submission outcomes

After you submit, Polytoken shows one of three outcomes:

• Submitted: Polytoken queued the event and the local flush completed.
• Delivery unconfirmed: Polytoken queued the event locally but could not confirm the delivery service received it. The event may or may not arrive.
• Not sent: the submission failed before Polytoken queued anything. Nothing was transmitted. You can edit and try again.

Polytoken does not promise delivery, retention, grouping, retries, queueing, or support follow-up.

Local feedback records

Polytoken also keeps an always-on local record of each feedback submission in $XDG_DATA_HOME/polytoken/logs/feedback.jsonl (~/.local/share/polytoken/logs/feedback.jsonl by default). Each JSON line contains the UTC submission time, submission outcome, Sentry event ID when Polytoken queued the event, session ID when available, the scrubbed text, and the names of selected attachments. Polytoken creates the file with mode 0600 and appends records under a file lock so concurrent submissions remain readable. Polytoken never deletes the file automatically. Manage or remove the file yourself when you no longer need the record.

Installation tag

Feedback carries an optional installation tag Polytoken reads from the local telemetry state. The tag is the same pseudonymous installation ID used in crash reports. If the telemetry state is unavailable, Polytoken omits the tag.

Feedback also carries the current session ID tag when Polytoken has a session identity. The session tag lets feedback correlate with the session that filed the report, and Polytoken omits the tag when the identity is unavailable.

Explicit feedback submission never repairs or attaches the installation ID if it was missing. Polytoken includes the tag only when the existing installation ID is valid.