feat(papercuts): a local feedback loop from one-tap report to verified fix

[nohat]

Goal

One tap (or none) to a report that carries everything an agent needs, then triage, a fix, a deploy, and a measured close, all on my machines. Reporting costs nothing, and the loop reaches "validated" without me being the test runner. Design page: docs/fork/papercuts.md. Capture (stages 1 and 2) is built; this tracks everything after it.

Decision, 2026-10-05

"i want a personal feedback loop that enforces privacy and security by keeping everything local to me and my environments implemented first. no need for different parts inside my loop to preserve privacy from other parts--that's just theater. only when we are thinking about possibly upstreaming the feature we can worry about privacy and security."

Consequences:

• Agents in the loop (triage, fixer, reviewer) read the whole record: screenshot, message text, note, full failure causes, trace slice. Capture gets richer, not more careful.
• Three real boundaries remain: (1) the public issue body, because the fork repo is public (a mechanical leak check in feat(papercuts): a triage job that turns new reports into issues #30); (2) egress from fork servers (bug(fork): fork servers send product analytics to upstream's PostHog by default #23); (3) upstreaming (question(papercuts): what must be true before offering this upstream or to other forks #34, parked).
• Dropped from the earlier proposal: a toPublicEvidence allowlist, a quarantine of free text from the fixer, and the sink layer. They are in question(papercuts): what must be true before offering this upstream or to other forks #34 for later.
• One cheap habit survives: the loop never takes instructions from GitHub text written by others.

Shape

report (tap, shake, palette, or the stall watchdog)
  -> record + trace slice on the receiving server        (immutable)   #26 #27 #28
  -> overlay: status history, signature, issue link      (append-only) #24 #29
  -> triage job (hourly, silent when idle) -> issue      (public-safe) #30
  -> I dispatch /defect-session papercuts                              #32 #31
  -> fix on fix/* -> gate -> fork-deploy                 (existing)
  -> overlay: fixed in <fork version>; soak; recur or close            #33

Waves

Wave 0 (now): decision record in docs/fork/papercuts.md; #23 egress.
Wave 1 (parallel): #24 overlay and CLI, #25 identity and retry, #26 server snapshot. #27 client capture follows #25 because both edit PapercutReporter.tsx; contract edits to papercut.ts are additive but will touch the same file, so merge in order.
Wave 2: #28 watchdog reports (after #26), #29 signature (after #24, and after about 10 real records from #26 and #27), #31 repro kit.
Wave 3: #30 triage job (after #24 and #29). Milestone: a stalled thread becomes a triaged issue with no tap and no message from me.
Wave 4: #32 dispatch mode, #33 recurrence, soak, close, and metrics.

Checklist

• bug(fork): fork servers send product analytics to upstream's PostHog by default #23 bug(fork): upstream PostHog on by default
• feat(papercuts): triage overlay and an agent-facing CLI (show, list, mark) #24 triage overlay and agent-facing CLI
• feat(papercuts): idempotent create, retry without losing the report, and a capability flag #25 idempotent create, retry, capability flag
• feat(papercuts): capture the server's full picture at report time #26 server snapshot v2 and trace slice
• feat(papercuts): capture the client's full picture and join it to server spans #27 client capture v2 and span join
• feat(server): file a papercut when the stall watchdog flags a turn #28 watchdog files a papercut
• feat(papercuts): a versioned signature and clusters for reports #29 signature and clusters
• feat(papercuts): a triage job that turns new reports into issues #30 triage job
• feat(papercuts): seed a worktree from a report so a fixer can reproduce it on real data #31 repro kit
• feat(papercuts): /defect-session papercuts dispatches fixes from clusters #32 /defect-session papercuts
• feat(papercuts): recurrence per build, soak, and automatic close #33 recurrence, soak, close, metrics
• question(papercuts): what must be true before offering this upstream or to other forks #34 parked: upstream and other forks

Assumptions recorded (change by comment)

• Triage state is overlay files plus a CLI, not an RPC or a database, because the live server owns the records and one user needs nothing larger.
• Signature is computed at triage and stored in the overlay, not at ingest, so the recipe can change without touching server code.
• Soak is 7 days after deploy; closing is reversible.
• Triage runs hourly and is silent on an empty list; dispatch stays mine (posture).
• Build identity is the fork version.

Not now (each needs an exhibit first)

A list view on web, desktop, and mobile (the CLI and the issues are the view; build it once they prove insufficient, and it must show status and undo on every surface). Android hang records (ApplicationExitInfo). A persistent outbox for web and desktop beyond retry in memory. An MCP toolkit for reports. Embeddings or LLM duplicate search over free text. Session replay. A priority model. Auto-dispatch of fixes. A sink layer.

Open question for later

Whether to auto-dispatch fixes for a class of cluster with a good track record. Decide with the numbers from #33, not before.

What success looks like

Median report to triaged issue under an hour, none of it hand-reconstructed. A failing test for most bounded clusters. Recurrence per build visible in one command. I touch the loop twice: the tap, and the dispatch.

[nohat]

Research notes behind #22, collected 2026-10-05. Sources are vendor docs or papers unless marked. Vendor figures and single-source claims are flagged.

Capture

• A retroactive buffer is the standard substitute for repro steps: Sentry feedback attaches replay up to 60 s before submit (https://docs.sentry.io/product/user-feedback/), Shake keeps 60 s of black-box data (https://help.shakebugs.com/en/articles/2741832-which-data-does-the-shake-sdk-track-and-report), Codex keeps a 4 MiB log ring (https://raw.githubusercontent.com/openai/codex/main/codex-rs/feedback/src/lib.rs).
• Readable breadcrumbs beat raw ids: Luciq records "Tapped on the button 'Send'" (https://docs.luciq.ai/docs/product-guides-reprosteps-and-automasking).
• Correlation ids carry across tools: Codex tags thread ids, Cursor uses a Request ID (https://docs.cursor.com/troubleshooting/request-reporting), Gemini CLI includes a session id (https://raw.githubusercontent.com/google-gemini/gemini-cli/main/packages/cli/src/ui/commands/bugCommand.ts).
• Developers rank steps to reproduce and stack traces highest; reporters find them hardest to supply (Zimmermann et al., FSE 2008, https://dl.acm.org/doi/10.1145/1453101.1453146). That is the case for auto-capture.
• Hangs need a path that does not depend on the hung thread: Sentry's app-hang watchdog (https://docs.sentry.io/platforms/react-native/configuration/app-hangs/); Android ApplicationExitInfo and setProcessStateSummary (https://developer.android.com/topic/performance/vitals/anr).
• Cap sizes and evict oldest first: Codex caps attachments; the ring already does.

Triage and fixing

• Group by a deterministic fingerprint first; embeddings only merge inside default groups and never split (https://docs.sentry.io/concepts/data-management/event-grouping/). For crash-like data, structured-signature embeddings beat LLM reranking (https://arxiv.org/pdf/2508.19449).
• Reproduction: LIBRO produced failing tests for about 33% of Defects4J bugs from prose (https://arxiv.org/pdf/2209.11515); AdbGPT replayed 81.3% of Android reports from step lists (https://arxiv.org/html/2306.01987v3). A ring buffer is nearer the second case.
• Failures concentrate in localization and in validate loops; single-file fixes succeed about 55-58% against 11-25% for multi-file (https://arxiv.org/html/2509.13941v1). Live-issue benchmarks score far below curated ones (OpenHands: 19% on SWE-bench-Live against 43% on Verified, via a summary: https://alphaxiv.org/benchmarks/shanghai-artificial-intelligence-laboratory/swe-bench-live). Treat as priors.
• Richer production context helps modestly: Sentry reports Autofix PR acceptance moving from 41% to 46% (vendor claim, https://blog.sentry.io/agents-need-production-context/). Sentry's 94.5% root-cause accuracy has no published method; do not use it as a base rate.
• Reviewing the reproducer matters: a fail-to-pass test can capture one manifestation (survey: https://arxiv.org/pdf/2506.17208).
• Verify fixes by effect against each new build, as ClusterFuzz does (https://blog.chromium.org/2012/04/fuzzing-for-security.html).
• Act only above a confidence floor: Mozilla's bugbug uses 60% (https://hacks.mozilla.org/?p=33364).
• Agent runs that fail run 12-82% longer than successes (https://arxiv.org/abs/2511.00197v1), which supports step caps.
• No controlled study compares inlining evidence against pulling it by tool. The plan inlines the signature and top spans and exposes show for the rest. That is a judgment call.

Security, for when the loop meets public text

• Public GitHub text fed to agents has been exploited in 2026 against several vendors' actions (summary: https://labs.cloudsecurityalliance.org/research/csa-research-note-ai-coding-agent-ci-prompt-injection-202608/). The loop's answer is narrow: it reads local records, writes issues, and does not read others' comments.
• Rule of Two and dual-LLM patterns (https://arxiv.org/pdf/2506.08837) are what question(papercuts): what must be true before offering this upstream or to other forks #34 would need if free text ever crosses a boundary.

Sinks and forks (for #34)

• Rageshake: configurable URL, absent means off, the receiver holds the GitHub token (https://github.com/element-hq/element-web/blob/develop/docs/config.md, https://github.com/matrix-org/rageshake).
• Sentry DSN guidance on dynamic delivery to shipped apps (https://docs.sentry.io/concepts/key-terms/dsn-explainer/).
• Home Assistant diagnostics with per-producer redaction (https://developers.home-assistant.io/docs/core/integration_diagnostics/).
• Homebrew and Flutter show what would be sent before sending (https://docs.brew.sh/Analytics).
• OTLP redirect variables (https://opentelemetry.io/docs/specs/otel/protocol/exporter/).

Not verified

Dosu, Rust triagebot, Home Assistant triage bots, Cursor Bugbot, Factory, and Codex cloud were not examined beyond search snippets. Slack, Discord, Notion, and Linear feedback flows were not verifiable. Cursor and Devin fix rates came from low-quality comparison blogs and are not used.