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. Polytoken may leave incidental paths or user-derived fragments in crash details when those fragments do not match its scrubbing patterns.

Default-on behavior

Polytoken enables automatic crash reporting by default after configuration loads successfully, including when only a project config exists. If configuration fails to load, Polytoken leaves crash reporting off and sends no automatic crash reports.

Automatic crash reporting also defaults to on for a headless daemon that the CLI starts with a valid 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, run polytoken config ui to 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 and the current TUI-log tail for recognized secret patterns, replacing matches such as API keys, bearer tokens, and password assignments with [REDACTED]. Daemon logs, other diagnostic artifacts, and screenshots remain raw and unsanitized. Review selected attachments before sending.

Press Esc in the feedback form to close it. If you have typed a message, Polytoken asks whether to discard the draft. Choose Discard draft to close the form and discard the message, or Keep editing to return to the form with the draft intact. An empty form closes immediately. While Polytoken sends feedback, the form ignores Esc 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 across multiple rows. Scroll through the list with the mouse wheel, keyboard, or scrollbar to reach every wrapped line. Clicking any row of a wrapped name highlights the artifact. To toggle attachment selection, click the checkbox on the artifact’s first row.

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. If an artifact changes identity, disappears, or loses content after the form opens, Polytoken reports a stale snapshot and does not transmit the artifact.

You can also add up to three screenshots from the system clipboard. Review screenshots for secrets or other sensitive information before attaching them.

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,000,000 bytes. All selected attachments count toward a 20 MiB aggregate attachment limit. Polytoken can send a large log when its bounded tail fits within the limit; adding screenshots can make the selected attachments exceed the limit.

Because the form estimates upload size before preparing attachments, the prepared attachments can exceed the aggregate limit even when the form enables Send. The form also blocks sending when a selected diagnostic artifact exceeds its individual size bound. Before transmission, Polytoken checks the prepared attachments and rejects any that exceed the individual or aggregate limit. Deselect attachments and try again if Polytoken reports a size error.

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. Polytoken transmitted nothing. You can edit and try again.

Local queueing does not guarantee delivery or a durable queue. Polytoken does not promise retention, grouping, retries, 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 to keep records from concurrent submissions readable. The file remains until you remove it. 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.

Polytoken also includes the current session ID as a tag to associate feedback with the session you submitted it from. When no session identity is available, Polytoken omits the session tag.

When you submit feedback, Polytoken includes an installation tag only if the existing installation ID is valid. Polytoken does not repair a missing installation ID during feedback submission.