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.

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

The Polytoken team stores submitted event data, including crash reports and feedback, on infrastructure it operates in the United States. Submissions travel through Cloudflare’s global network before they reach that infrastructure, so transit processing can occur outside the United States. For triage, the Polytoken team may copy feedback and its attachments to Jira and Confluence, which Atlassian hosts at locations of its choosing. See the privacy policy for how long each destination keeps a report.

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]. Diagnostic attachments remain raw and unsanitized. Review selected attachments before sending.

Pressing Esc in the feedback form protects an unsent draft. If you have typed a message, Polytoken asks whether to discard it: choosing Discard draft closes the form and throws the message away, and choosing Keep editing returns to the form with the draft intact. If you have not typed anything, Polytoken closes the form immediately. While a submission is being sent, Polytoken ignores the Escape key until the outcome appears.

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 lists available diagnostic artifacts, including the daemon log, runtime liveness trail, current session log, and subagent logs. Instrumented development builds also list an additional CPU-profile artifact. The current TUI log appears as an additional row when it contains content. Each row has its own selection control. The first available daemon-log row and the current TUI-log row start selected; other artifact rows start unselected. Unavailable rows remain visible with their reason. Long artifact names wrap onto multiple rows; the list scrolls by the rows you see, so every wrapped line is reachable with the scroll wheel, the keyboard, or by dragging the scrollbar, and clicking any wrapped row selects that artifact while the selection checkbox responds only on the row that starts it.

Polytoken records each artifact’s identity and content digest when the form opens, then verifies the artifact again when you retrieve it. The send screen shows each snapshot’s human-readable size. Diagnostic attachments remain raw and unsanitized. Polytoken scrubs typed feedback only. If an artifact was replaced, removed, or truncated after the form opened, Polytoken reports a stale snapshot and does not transmit the artifact. Polytoken keeps no open file handles for feedback artifacts while the form remains open.

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, reporting 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.