Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): record a confirmed send whose sidecar is unreadable (PRD-8239) (#3782)
Andrew Mikofalvydc3365b1dc61
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdxindex c1ddc09cb..638038021 100644--- a/docs/content/reference/what-open-knowledge-writes.mdx+++ b/docs/content/reference/what-open-knowledge-writes.mdx@@ -137,7 +137,7 @@ On each launch and project open, the app also runs **repair sweeps**: it rewrite| `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No || `~/.ok/themes/` | Your saved color themes from the [Themes plugin](../plugins/themes.mdx), one Tinted Theming base16 YAML file per theme, written when you create or edit a theme | No || `~/.ok/mcp-status.json` | First-launch MCP consent record | No |-| `~/.ok/logs/`, `~/.ok/bug-reports/` | Desktop and CLI logs, and bug-report bundles from `ok bug-report` and the app's **Help → Report a bug…** dialog (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`). Each report from the dialog also gets a small YAML record holding its send state and a secret-redacted copy of the note you wrote, so report history can still show what a report was about. The zip is deleted once the report is sent; the record is kept, and both go when you delete the report from report history | No |+| `~/.ok/logs/`, `~/.ok/bug-reports/` | Desktop and CLI logs, and bug-report bundles from `ok bug-report` and the app's **Help → Report a bug…** dialog (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`). Each report from the dialog also gets a small YAML record holding its send state and a secret-redacted copy of the note you wrote, so report history can still show what a report was about. The zip is deleted once the report is sent; the record is kept, and both go when you delete the report from report history. If that record ever can't be read back, OpenKnowledge leaves it exactly as it is rather than overwriting your note, and writes a second tiny `.sent.yaml` file beside it when a report does send, so history still shows it as sent instead of offering to send it again | No || `~/.ok/bin/`, `~/.ok/env.sh` | `PATH` shim (see [Shell and `PATH`](#shell-and-path) above) | No |**Auth tokens** (for GitHub sync, sharing, and cloning) are stored in your OS credential store under the service name `open-knowledge` — the **Keychain** on macOS, **Credential Manager** on Windows, and the Secret Service keyring (libsecret) on Linux. The `~/.ok/auth.yml` file is only a fallback for headless environments where the credential store isn't reachable; when it becomes available, the token is migrated into it and the file copy is removed.@@ -263,7 +263,7 @@ Disable all three with `OK_RECLAIM_DISABLE=1`.| `~/.ok/stats.jsonl` | Local "open with AI" handoff stats — local-only, no phone-home | No || `~/.ok/themes/` | Your saved color themes from the [Themes plugin](../plugins/themes.mdx), one Tinted Theming base16 YAML file per theme, written when you create or edit a theme | No || `~/.ok/logs/` | CLI logs (`cli.<date>.log`), size- and age-capped | No |-| `~/.ok/bug-reports/` | Bug-report bundles from `ok bug-report` — the desktop app's **Help → Report a bug…** dialog writes here too (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`). A report filed from the dialog also leaves a small YAML record beside its bundle, holding the report's send state and a secret-redacted copy of the note you wrote so report history can name it. That record outlives the bundle: the zip is deleted once the report is sent, and the record is kept until you delete the report from report history | No |+| `~/.ok/bug-reports/` | Bug-report bundles from `ok bug-report` — the desktop app's **Help → Report a bug…** dialog writes here too (`ok diagnose bundle` writes into the project, under `.ok/local/diagnostics/`). A report filed from the dialog also leaves a small YAML record beside its bundle, holding the report's send state and a secret-redacted copy of the note you wrote so report history can name it. That record outlives the bundle: the zip is deleted once the report is sent, and the record is kept until you delete the report from report history. If the record ever can't be read back, OpenKnowledge leaves it exactly as it is rather than overwriting your note, and writes a second tiny `.sent.yaml` file beside it when a report does send. That marker holds only the send time and the report's reference, never your note, and it is removed with the rest of the report | No |**Auth tokens** (for GitHub sync, sharing, and cloning) are stored in your operating system's secure credential store when one is available — the macOS **Keychain** (service `open-knowledge`), or the platform equivalent (Windows Credential Manager, Linux Secret Service) — falling back to a `0600` `~/.ok/auth.yml` file on headless systems (a Linux server, CI) where none is reachable.diff --git a/packages/cli/src/commands/bug-report-bundle.test.ts b/packages/cli/src/commands/bug-report-bundle.test.tsindex 53f648628..80579f6c3 100644--- a/packages/cli/src/commands/bug-report-bundle.test.ts+++ b/packages/cli/src/commands/bug-report-bundle.test.ts@@ -17,6 +17,7 @@ import {collectUserLogFiles,DESKTOP_BUNDLE_ID,defaultBugReportZipPath,+ MAX_BUNDLED_LEDGER_REPORTS,okBugReportsDir,} from './bug-report-bundle.ts';@@ -778,8 +779,76 @@ describe('collectStandardBundle — bundle scope disclosure', () => {expect(readme.slice(readme.indexOf('## Privacy'))).not.toContain('Send history:');expect(listZipEntries(zipPath).filter((e) => e.startsWith('state/bug-reports/'))).toEqual([]);});++ // The `sent` marker's `.yaml` extension is load-bearing on THIS end: the+ // desktop store names it that way precisely so this allowlist carries it+ // without a second rule. For a report whose sidecar could not be read when+ // its send landed, the marker is the ONLY readable send record in the+ // bundle — narrowing the filter would drop exactly the evidence for the+ // failure class it exists to make diagnosable, and nothing else would notice.+ test('stages a sent marker alongside the sidecar it stands in for', async () => {+ const reportsDir = makeTmpDir('ok-bugreport-ledger-');+ const base = '2026-08-19T16-42-03-547Z-bugreport';+ writeFileSync(join(reportsDir, `${base}.yaml`), 'id: [unreadable\n : :');+ writeFileSync(+ join(reportsDir, `${base}.sent.yaml`),+ `version: 1\nid: ${base}.zip\nsentAt: 2026-08-19T16:45:00.000Z\nreference: OK-4821\n`,+ );+ const outputPath = join(makeTmpDir(), 'report.zip');++ const { zipPath } = await collectStandardBundle({+ projectDir: makeProjectDir('bundle-proj'),+ redact: true,+ outputPath,+ userLogsDir: makeTmpDir(),+ bugReportLedgerFiles: collectBugReportLedgerFiles(reportsDir),+ });++ const staged = listZipEntries(zipPath).filter((e) => e.startsWith('state/bug-reports/'));+ expect(staged).toContain(`state/bug-reports/${base}.sent.yaml`);+ expect(staged).toContain(`state/bug-reports/${base}.yaml`);+ // And the reference survives staging, which is the point of carrying the+ // marker rather than only the sidecar that could not record it.+ expect(readZipEntry(zipPath, `state/bug-reports/${base}.sent.yaml`)).toContain('OK-4821');+ });++ // Slicing a sorted FILE list cuts at a fixed index, and nothing aligns that+ // index to a report boundary — adjacency does not prevent a split. The half+ // it would drop is the marker, which sorts first, so the bundle would ship+ // the corrupt sidecar that proves nothing and drop the only readable record+ // of the send, for exactly the population the marker exists to make+ // diagnosable.+ test('the ledger cap evicts whole reports, never half of a marker pair', () => {+ const reportsDir = makeTmpDir('ok-bugreport-ledger-');+ const bases: string[] = [];+ // Two reports past the cap, every one carrying BOTH files, so a file-counting+ // slice necessarily cuts between a marker and its own sidecar.+ for (let i = 1; i <= MAX_BUNDLED_LEDGER_REPORTS + 2; i += 1) {+ const base = `2026-08-19T16-42-${String(i).padStart(2, '0')}-000Z-bugreport`;+ bases.push(base);+ writeFileSync(join(reportsDir, `${base}.yaml`), `id: ${base}.zip\n`);+ writeFileSync(join(reportsDir, `${base}.sent.yaml`), `id: ${base}.zip\nreference: OK-${i}\n`);+ }++ const listed = collectBugReportLedgerFiles(reportsDir).map((p) => basename(p));++ for (const base of bases) {+ expect(listed.includes(`${base}.sent.yaml`)).toBe(listed.includes(`${base}.yaml`));+ }+ // And the cap still bounds the bundle: the two oldest reports are gone whole.+ expect(listed).toHaveLength(MAX_BUNDLED_LEDGER_REPORTS * 2);+ expect(listed).not.toContain(`${nthBase(bases, 0)}.yaml`);+ expect(listed).toContain(`${nthBase(bases, -1)}.yaml`);+ });});+/** Indexed access that asserts presence (the test controls the array). */+function nthBase(bases: readonly string[], index: number): string {+ const value = bases.at(index);+ if (value === undefined) throw new Error(`no base at index ${index}`);+ return value;+}+describe('collectStandardBundle — system-wide (no projectDir)', () => {test('captures user logs + sysinfo only, with a null slug', async () => {const userLogsDir = makeTmpDir();diff --git a/packages/cli/src/commands/bug-report-bundle.ts b/packages/cli/src/commands/bug-report-bundle.tsindex 744ff003a..630fd7cb1 100644--- a/packages/cli/src/commands/bug-report-bundle.ts+++ b/packages/cli/src/commands/bug-report-bundle.ts@@ -18,6 +18,7 @@ import { basename, dirname, join, resolve } from 'node:path';import {type BundleManifest,type BundleRedaction,+ REPORT_SENT_MARKER_SUFFIX,REPORT_SIDECAR_BUNDLE_DIR,SERVER_CRASH_LOG,} from '@inkeep/open-knowledge-core';@@ -281,17 +282,33 @@ export function collectShipItLogFiles(}/**- * How many sidecars a bundle carries. Retention keeps reports around, so this- * directory grows without limit on a machine that files often, and a bundle- * must not scale with a reporter's history. Each file is small and bounded by- * construction (the writer caps the attempt list), so the count is the only- * bound needed.+ * How many REPORTS a bundle carries ledger records for. Retention keeps reports+ * around, so this directory grows without limit on a machine that files often,+ * and a bundle must not scale with a reporter's history. Each file is small and+ * bounded by construction (the writer caps the attempt list), so the count is+ * the only bound needed.+ *+ * Reports rather than files, because a report whose sidecar was unreadable at+ * send time leaves two: the sidecar and a `sent` marker. Counting files would+ * let the cut fall BETWEEN a pair, and adjacency in the sorted listing does not+ * prevent that — nothing aligns a fixed index to a report boundary. The half it+ * would drop is the marker, which for exactly that report is the only readable+ * send record, while keeping the corrupt sidecar that proves nothing. So the+ * unit of eviction is the report, and a pair is kept or dropped whole.*/-const MAX_BUNDLED_LEDGER_FILES = 25;+export const MAX_BUNDLED_LEDGER_REPORTS = 25;/**- * The per-report send ledger: one small YAML sidecar per report, recording- * every send attempt with its outcome and reason.+ * The per-report send ledger: a small YAML record per report, recording every+ * send attempt with its outcome and reason.+ *+ * Usually that is one file, the report's sidecar. A report whose sidecar could+ * not be read when its send landed leaves a second, `<base>-bugreport.sent.yaml`,+ * holding the send time and the intake reference — for exactly that report the+ * marker IS the send record, since the sidecar beside it is the unreadable one.+ * The `.yaml` allowlist below is what carries it, which is why the marker is+ * named with that extension rather than a bare `.sent`; a test pins the+ * coupling, because narrowing the filter would drop it silently.** This is the artifact that answers "did the send fail before, and how" — and* the only one that still answers it later, because `desktop.*.log` rotates on@@ -299,21 +316,37 @@ const MAX_BUNDLED_LEDGER_FILES = 25;* report about a failed send carries no account of the failure unless the* reporter happens to file it the same day, on a machine we can read.*- * Sidecars ONLY: `*.yaml` is an allowlist, not a filter, so the zips sitting+ * Records ONLY: `*.yaml` is an allowlist, not a filter, so the zips sitting* beside them in the same directory cannot be swept in. That matters twice —* a bundle must not contain other bundles, and the zips are the bulk of the* directory.** Newest kept, ranked by name: report ids are timestamp-prefixed, so- * lexicographic order IS chronological order and no `stat` call is needed.+ * lexicographic order IS chronological order and no `stat` call is needed. A+ * marker shares its report's timestamp prefix, so grouping by that prefix+ * collects each report's files without a second sort.*/export function collectBugReportLedgerFiles(bugReportsDir: string): string[] {if (!existsSync(bugReportsDir)) return [];try {- return readdirSync(bugReportsDir)+ const byReport = new Map<string, string[]>();+ for (const name of readdirSync(bugReportsDir).filter((name) => name.endsWith('.yaml'))- .sort()- .slice(-MAX_BUNDLED_LEDGER_FILES)+ .sort()) {+ // Both of a report's files reduce to the same key, so they group together+ // and the slice below can never keep one without the other.+ const base = name.endsWith(REPORT_SENT_MARKER_SUFFIX)+ ? name.slice(0, -REPORT_SENT_MARKER_SUFFIX.length)+ : name.slice(0, -'.yaml'.length);+ const files = byReport.get(base);+ if (files === undefined) byReport.set(base, [name]);+ else files.push(name);+ }+ // Map preserves insertion order and the names arrived sorted, so the report+ // keys are already oldest-first.+ return [...byReport.values()]+ .slice(-MAX_BUNDLED_LEDGER_REPORTS)+ .flat().map((name) => join(bugReportsDir, name));} catch {// An unreadable reports dir must cost the ledger, never the report the@@ -654,7 +687,7 @@ export async function collectStandardBundle(: []),...(ledgerEntries.length > 0? [- 'Send history: one small record per bug report previously generated',+ 'Send history: a small record for each bug report previously generated','on this machine — when it was generated, whether sending it','succeeded, and why it failed if it did. This is what makes a failed','send diagnosable at all. It is machine-wide rather than scoped to',diff --git a/packages/core/src/bug-report-sidecar/schema.ts b/packages/core/src/bug-report-sidecar/schema.tsindex b66fe9b8e..9da39bd73 100644--- a/packages/core/src/bug-report-sidecar/schema.ts+++ b/packages/core/src/bug-report-sidecar/schema.ts@@ -170,3 +170,48 @@ export const ReportSidecarSchema = z.looseObject({});export type ReportSidecar = z.infer<typeof ReportSidecarSchema>;++/**+ * Filename suffix of the sibling `sent` marker, replacing a report id's `.zip`.+ *+ * Deliberately still a `.yaml`: the diagnostic-bundle ledger collector stages+ * `*.yaml` out of the reports directory, and for a report whose sidecar is+ * unreadable the marker IS the send record a triager needs, so riding that rule+ * costs nothing and a second rule could drift from it. It cannot collide with a+ * sidecar path — `REPORT_ID_PATTERN` ends in `-bugreport[-N].zip`, so a sidecar+ * is never named `*.sent.yaml`.+ */+export const REPORT_SENT_MARKER_SUFFIX = '.sent.yaml';++/**+ * The marker's own schema version, independent of the sidecar's. The two files+ * are written by one module and deleted together, but their SHAPES evolve+ * separately: a breaking change to the sidecar says nothing about a document+ * that holds a send time and a reference. Sharing the sidecar's constant would+ * silently restamp markers whose shape never changed.+ */+export const REPORT_SENT_MARKER_SCHEMA_VERSION = 1;++/**+ * The sibling `sent` marker: the record of a send the intake confirmed but the+ * sidecar could not be made to hold, because it was unreadable and rewriting it+ * would have erased the reporter's note.+ *+ * Read PRESENCE-FIRST. The file existing is the fact — "the intake accepted+ * this bundle" — and its contents are best-effort detail on top. A marker that+ * fails to parse still stops the row inviting a duplicate upload; it just+ * cannot name the reference. Every field but the `.catch`-guarded `version` is+ * therefore optional: a half-written marker must degrade to less detail, never+ * to "no send".+ */+export const ReportSentMarkerSchema = z.looseObject({+ version: z.number().int().catch(REPORT_SENT_MARKER_SCHEMA_VERSION),+ /** The report's zip basename — self-describing, as the sidecar's `id` is. */+ id: z.string().optional(),+ /** ISO-8601 time the intake confirmed the send. */+ sentAt: z.string().optional(),+ /** Intake reference — the reporter's handle on the report with support. */+ reference: z.string().optional(),+});++export type ReportSentMarker = z.infer<typeof ReportSentMarkerSchema>;diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 25ed48fc5..f8d149216 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -13,9 +13,13 @@ export {isReportIdShape,normalizeReportSidecarState,REPORT_ID_PATTERN,+ REPORT_SENT_MARKER_SCHEMA_VERSION,+ REPORT_SENT_MARKER_SUFFIX,REPORT_SIDECAR_BUNDLE_DIR,REPORT_SIDECAR_SCHEMA_VERSION,REPORT_SIDECAR_STATES,+ type ReportSentMarker,+ ReportSentMarkerSchema,type ReportSidecar,type ReportSidecarAttempt,type ReportSidecarKnownState,diff --git a/packages/core/src/logger-types.ts b/packages/core/src/logger-types.tsindex 2c65c082f..7c2ff26f5 100644--- a/packages/core/src/logger-types.ts+++ b/packages/core/src/logger-types.ts@@ -296,11 +296,12 @@ export type OkBugReportListResult =/*** Result of the desktop `ok:bug-report:dispatch` delete operation. Removes a- * report's zip and sidecar by `id` after a containment + id-shape check. Never- * thrown across the IPC boundary.+ * report's zip, sidecar and `sent` marker by `id` after a containment ++ * id-shape check. Never thrown across the IPC boundary.* - `id-invalid` — the id failed the timestamp-basename shape / containment gate.* - `in-flight` — the report's own send is currently in progress in this process.- * - `not-found` — no zip and no sidecar for the id.+ * - `not-found` — none of the three files exists for the id. A marker can+ * outlive the other two, and deleting one is not a no-op.* - `io-error` — a filesystem removal failed.*/export type OkBugReportDeleteResult =diff --git a/packages/desktop/src/main/bug-report-sidecar.test.ts b/packages/desktop/src/main/bug-report-sidecar.test.tsindex 39391f571..9b7fa4186 100644--- a/packages/desktop/src/main/bug-report-sidecar.test.ts+++ b/packages/desktop/src/main/bug-report-sidecar.test.ts@@ -27,11 +27,14 @@ import { afterEach, describe, expect, test } from 'vitest';import {createBugReportSidecarStore,createInFlightRegistry,+ createSidecarScanWarnRegistry,deleteReport,listReports,+ MAX_REMEMBERED_SCAN_WARNINGS,readReportSidecar,reconcileStaleUploading,runRetentionSweep,+ sentMarkerPathForId,sidecarPathForId,writeReportSidecar,zipPathForId,@@ -140,6 +143,30 @@ async function seedReport(return id;}+/** Collects a store's warn calls so a skipped or deduplicated write can be inspected. */+function makeWarnRecorder() {+ const warns: { data: unknown; message: string }[] = [];+ return {+ warns,+ logger: {+ warn: (data: unknown, message: string) => {+ warns.push({ data, message });+ },+ },+ };+}++/**+ * Write a `sent` marker by hand — the shape a terminal write that could not+ * touch the sidecar leaves beside it.+ */+function seedSentMarker(dir: string, id: string, reference: string, sentAt?: string): void {+ writeFileSync(+ sentMarkerPathForId(dir, id),+ `version: 1\nid: ${id}\nsentAt: ${sentAt ?? ridCreatedAt(1)}\nreference: ${reference}\n`,+ );+}+describe('writeReportSidecar / readReportSidecar', () => {test('round-trips a generated sidecar to disk as YAML next to the zip', async () => {const dir = makeTmpDir();@@ -781,19 +808,6 @@ describe('reconcileStaleUploading', () => {});describe('send hooks — an unreadable sidecar is preserved, not overwritten', () => {- /** Collects the store's warn calls so a skipped write can be shown to be loud. */- function makeWarnRecorder() {- const warns: { data: unknown; message: string }[] = [];- return {- warns,- logger: {- warn: (data: unknown, message: string) => {- warns.push({ data, message });- },- },- };- }-/** Seed a real note-bearing report, then make its sidecar unreadable in place. */async function seedUnreadable(dir: string, note: string): Promise<string> {const id = await seedReport(dir, 1, { state: 'generated', note });@@ -815,22 +829,26 @@ describe('send hooks — an unreadable sidecar is preserved, not overwritten', (expect(warns.some((w) => w.message.includes('sidecar unreadable'))).toBe(true);});- test('onSendResult leaves the record alone and logs the outcome it could not store', async () => {+ test('onSendResult leaves the record alone, and the reference survives it', async () => {const dir = makeTmpDir();const id = await seedUnreadable(dir, 'sync hung on a large repo');const before = readFileSync(sidecarPathForId(dir, id));const { logger, warns } = makeWarnRecorder();const store = createBugReportSidecarStore({ dir, logger });- await store.sendHooks.onSendResult(id, { kind: 'sent', reference: 'REF-8221' });+ await store.sendHooks.onSendResult(id, { kind: 'sent', reference: 'REF-PRESERVE' });expect(readFileSync(sidecarPathForId(dir, id))).toEqual(before);// A confirmed send's reference is the reporter's only handle on the report- // with support. If it cannot be stored it has to be recoverable from the- // log, or the send becomes untraceable.- const skipped = warns.find((w) => w.message.includes('send outcome not recorded'));+ // with support, so it has to survive the skipped write. The log carries it,+ // and the marker beside the untouched sidecar records it durably.+ const skipped = warns.find((w) => w.message.includes('not written to the sidecar'));expect(skipped).toBeDefined();- expect(JSON.stringify(skipped?.data)).toContain('REF-8221');+ expect(JSON.stringify(skipped?.data)).toContain('REF-PRESERVE');+ expect(readFileSync(sentMarkerPathForId(dir, id), 'utf-8')).toContain('REF-PRESERVE');+ // The two side effects that follow, asserted rather than left implicit:+ // retention reclaims the zip of a report now known to have sent.+ expect(existsSync(zipPathForId(dir, id))).toBe(false);});test('the in-flight lock is released even when the write is skipped', async () => {@@ -883,6 +901,433 @@ describe('send hooks — an unreadable sidecar is preserved, not overwritten', ();});+/**+ * A send the intake CONFIRMED is a fact the store has to record, and the+ * store deliberately refuses to rewrite the one file that could record it —+ * an unreadable sidecar holds the reporter's prose. These pin+ * the sibling marker that carries the fact instead — without which the row+ * keeps offering Retry (a duplicate upload of a bundle intake already took),+ * hides the reference support asks for, and never leaves the unsent pool, so+ * cap eviction eventually unlinks the very note the refusal exists to protect.+ */+describe('send hooks — a confirmed send is recorded even when the sidecar is unreadable', () => {+ /** A note-bearing report with its zip, whose sidecar is then made unparseable. */+ async function seedUnreadableWithZip(dir: string, note: string): Promise<string> {+ const id = await seedReport(dir, 1, { state: 'generated', note });+ writeFileSync(sidecarPathForId(dir, id), 'state: [unclosed\n bad: : :\n');+ return id;+ }++ test('the row reads sent, keeps its reference, and stops offering Retry', async () => {+ const dir = makeTmpDir();+ const id = await seedUnreadableWithZip(dir, 'the editor froze after a paste');+ const store = createBugReportSidecarStore({ dir });++ await store.sendHooks.onSendResult(id, { kind: 'sent', reference: 'REF-LISTROW' });++ const result = await store.list();+ if (!result.ok) throw new Error('expected ok');+ const row = nth(result.reports, 0);+ expect(row.id).toBe(id);+ expect(row.state).toBe('sent');+ // Retrying a report intake already accepted re-uploads the same bundle.+ expect(row.retryable).toBe(false);+ // The reference is the reporter's only handle on the report with support.+ expect(row.reference).toBe('REF-LISTROW');+ // The record itself is still unreadable, so the row stays degraded.+ expect(row.degraded).toBe(true);+ });++ test('the marker is a NEW file — the sidecar stays byte-identical', async () => {+ const dir = makeTmpDir();+ const id = await seedUnreadableWithZip(dir, 'sync hung on a large repo');+ const before = readFileSync(sidecarPathForId(dir, id));+ const store = createBugReportSidecarStore({ dir });++ await store.sendHooks.onSendResult(id, { kind: 'sent', reference: 'REF-MARKER' });++ // The preserve-what-we-cannot-read invariant is untouched: the record is+ // not rewritten. The fact lands beside it instead.+ expect(readFileSync(sidecarPathForId(dir, id))).toEqual(before);+ expect(readFileSync(sentMarkerPathForId(dir, id), 'utf-8')).toContain('REF-MARKER');+ });++ test('no marker is left behind when the sidecar itself recorded the send', async () => {+ const dir = makeTmpDir();+ const id = await seedReport(dir, 1, { state: 'uploading', note: 'a readable record' });+ const store = createBugReportSidecarStore({ dir });++ await store.sendHooks.onSendResult(id, { kind: 'sent', reference: 'REF-NORMAL' });++ // The marker is the fallback for a record that could not be written, not a+ // second copy of every send.+ expect(existsSync(sentMarkerPathForId(dir, id))).toBe(false);+ expect((await readSidecarValue(sidecarPathForId(dir, id)))?.reference).toBe('REF-NORMAL');+ });++ test('a non-sent outcome is not marked — those stay retryable by design', async () => {+ const dir = makeTmpDir();+ const id = await seedUnreadableWithZip(dir, 'offline while sending');+ const store = createBugReportSidecarStore({ dir });++ await store.sendHooks.onSendResult(id, { kind: 'upload-failed', reason: 'offline' });++ expect(existsSync(sentMarkerPathForId(dir, id))).toBe(false);+ expect(existsSync(zipPathForId(dir, id))).toBe(true);+ });++ test('retention reclaims the zip of a confirmed send it could only mark', async () => {+ const dir = makeTmpDir();+ const id = await seedUnreadableWithZip(dir, 'a note behind a corrupt file');+ const store = createBugReportSidecarStore({ dir });++ await store.sendHooks.onSendResult(id, { kind: 'sent', reference: 'REF-RECLAIM' });++ expect(existsSync(zipPathForId(dir, id))).toBe(false);+ // The unreadable sidecar is still not ours to touch.+ expect(existsSync(sidecarPathForId(dir, id))).toBe(true);+ });++ test('the report leaves the unsent pool, so cap eviction never unlinks its note', async () => {+ const dir = makeTmpDir();+ // The sent-but-unrecordable report is the OLDEST, which is precisely the+ // one the unsent-count cap evicts first — taking the zip AND the sidecar.+ const sentId = await seedUnreadableWithZip(dir, 'crashed while renaming a folder');+ const store = createBugReportSidecarStore({ dir });+ await store.sendHooks.onSendResult(sentId, { kind: 'sent', reference: 'REF-CAP' });++ for (let i = 2; i <= MAX_UNSENT_REPORT_COUNT + 2; i += 1) {+ await seedReport(dir, i, { state: 'generated' });+ }+ await runRetentionSweep(dir, createInFlightRegistry());++ expect(existsSync(sidecarPathForId(dir, sentId))).toBe(true);+ expect(existsSync(sentMarkerPathForId(dir, sentId))).toBe(true);+ // The cap did fire — the oldest genuinely-unsent report was evicted, so+ // the survival above is not a vacuous pass.+ expect(existsSync(zipPathForId(dir, rid(2)))).toBe(false);+ });++ test('an unparseable marker still means sent — its existence is the record', async () => {+ const dir = makeTmpDir();+ const id = await seedReport(dir, 1, { state: 'generated' });+ writeFileSync(sentMarkerPathForId(dir, id), 'not: [yaml\n : :');++ const result = await listReports(dir);+ if (!result.ok) throw new Error('expected ok');+ const row = nth(result.reports, 0);+ expect(row.state).toBe('sent');+ expect(row.retryable).toBe(false);+ // Nothing left to recover the reference from, so support is not offered —+ // but a duplicate upload is not invited either.+ expect(row.reference).toBeUndefined();+ });++ // The other marker trigger: the sidecar READS fine and its WRITE throws. A+ // read-only reports directory is the portable way to force that — `rename`+ // needs write permission on the directory, not on the target file, so no file+ // mode reaches this arm. The same directory then blocks the marker write too,+ // which is why this pins the branch being taken and the failure being loud+ // rather than the marker landing.+ test.skipIf(process.getuid?.() === 0 || process.platform === 'win32')(+ 'a readable sidecar whose write fails still reaches the marker, loudly',+ async () => {+ const dir = makeTmpDir();+ const id = await seedReport(dir, 1, { state: 'uploading', note: 'a readable record' });+ const before = readFileSync(sidecarPathForId(dir, id));+ const { logger, warns } = makeWarnRecorder();+ const store = createBugReportSidecarStore({ dir, logger });+ chmodSync(dir, 0o555);++ await store.sendHooks.onSendResult(id, { kind: 'sent', reference: 'REF-THROWN' });++ chmodSync(dir, 0o755);+ // The sidecar was readable, so this is the thrown-write arm, not the+ // skipped-read one. Asserting WHICH warn fired is what separates them.+ expect(warns.some((w) => w.message.includes('failed to write the send result sidecar'))).toBe(+ true,+ );+ expect(warns.some((w) => w.message.includes('not written to the sidecar'))).toBe(false);+ // The marker attempt only happens when the sidecar did not record the+ // send, so this warn is the proof the branch was taken.+ const markerFailed = warns.find((w) => w.message.includes('failed to write the sent marker'));+ expect(markerFailed).toBeDefined();+ expect(JSON.stringify(markerFailed?.data)).toContain('REF-THROWN');+ expect(readFileSync(sidecarPathForId(dir, id))).toEqual(before);+ },+ );++ test('a marked send keeps its corrupt sidecar out of the orphan sweep', async () => {+ const dir = makeTmpDir();+ const id = await seedUnreadableWithZip(dir, 'the note is in there as raw text');+ const store = createBugReportSidecarStore({ dir });++ // Reclaiming the zip is what makes this reachable: a durably-corrupt+ // sidecar with no bundle is exactly the orphan sweep's shape, so marking a+ // send would otherwise hand it straight to that unlink. With the marker the+ // report is a TOMBSTONE, bounded by the tombstone cap instead.+ await store.sendHooks.onSendResult(id, { kind: 'sent', reference: 'REF-ORPHAN' });+ await runRetentionSweep(dir, createInFlightRegistry());+ await runRetentionSweep(dir, createInFlightRegistry());++ expect(existsSync(zipPathForId(dir, id))).toBe(false);+ expect(existsSync(sidecarPathForId(dir, id))).toBe(true);+ expect(readFileSync(sidecarPathForId(dir, id), 'utf-8')).toContain('unclosed');+ });++ test('delete removes the marker along with the sidecar', async () => {+ const dir = makeTmpDir();+ const id = await seedUnreadableWithZip(dir, 'a note behind a corrupt file');+ const store = createBugReportSidecarStore({ dir });+ await store.sendHooks.onSendResult(id, { kind: 'sent', reference: 'REF-DELETE' });++ expect(await store.remove(id)).toEqual({ ok: true });+ expect(existsSync(sentMarkerPathForId(dir, id))).toBe(false);+ expect(existsSync(sidecarPathForId(dir, id))).toBe(false);+ });++ test('a delete racing the marker write is refused, not left to resurrect the report', async () => {+ const dir = makeTmpDir();+ const id = await seedUnreadableWithZip(dir, 'a note behind a corrupt file');+ const store = createBugReportSidecarStore({ dir });+ expect(await store.sendHooks.onSendStart(id)).toEqual({ proceed: true });++ // Issued WITHOUT awaiting the send, so it reaches the in-flight check while+ // the terminal record is still being written — the same interleaving a+ // delete IPC gets on the event loop. The lock is what has to refuse it: if+ // it were released before the marker write, this delete would unlink the+ // zip and the sidecar, report success, and then the marker would land and+ // resurrect the report as a phantom `sent` tombstone on the next scan.+ const send = store.sendHooks.onSendResult(id, { kind: 'sent', reference: 'REF-RACE' });+ const removed = await store.remove(id);+ await send;++ expect(removed).toEqual({ ok: false, reason: 'in-flight' });+ expect(existsSync(sentMarkerPathForId(dir, id))).toBe(true);+ });++ // Presence-first is what makes the two DESTRUCTIVE guards safe, and both are+ // otherwise exercised only with markers that parse. A refactor swapping+ // `sentMarkerPresent` for a truthy check on the parsed contents would pass+ // every other test here while restoring the note-destruction path.+ test('the orphan sweep spares a corrupt sidecar whose marker does not parse either', async () => {+ const dir = makeTmpDir();+ const id = await seedUnreadableWithZip(dir, 'a note behind a corrupt file');+ writeFileSync(sentMarkerPathForId(dir, id), 'not: [yaml\n : :');+ // The zip already reclaimed is the shape the orphan sweep keys on.+ rmSync(zipPathForId(dir, id));++ await runRetentionSweep(dir, createInFlightRegistry());++ expect(existsSync(sidecarPathForId(dir, id))).toBe(true);+ expect(existsSync(sentMarkerPathForId(dir, id))).toBe(true);+ });++ test('boot reconciliation spares a report whose marker does not parse either', async () => {+ const dir = makeTmpDir();+ const id = await seedReport(dir, 1, { state: 'uploading', note: 'stuck mid-send' });+ writeFileSync(sentMarkerPathForId(dir, id), 'not: [yaml\n : :');++ expect(await reconcileStaleUploading(dir)).toBe(0);+ expect((await readSidecarValue(sidecarPathForId(dir, id)))?.state).toBe('uploading');+ });++ test('a marker-only report lists as sent, sorted by its send time', async () => {+ const dir = makeTmpDir();+ const id = rid(1);+ // What the tombstone cap and a reclaimed sidecar leave behind. The whole+ // list is one try/catch, so a throw in this branch would black out the+ // history dialog rather than misrender one row.+ seedSentMarker(dir, id, 'REF-ALONE-ROW', ridCreatedAt(1));++ const result = await listReports(dir);+ if (!result.ok) throw new Error('expected ok');+ const row = nth(result.reports, 0);+ expect(row.state).toBe('sent');+ expect(row.retryable).toBe(false);+ expect(row.reference).toBe('REF-ALONE-ROW');+ // The marker's send time is the only timestamp such a row has.+ expect(row.createdAt).toBe(ridCreatedAt(1));+ expect(row.zipExists).toBe(false);+ expect(row.zipDeleted).toBe(true);+ });++ test('a marker alone is a deletable record, not a not-found', async () => {+ const dir = makeTmpDir();+ const id = rid(1);+ // Everything else has been reclaimed; the marker is all that is left.+ seedSentMarker(dir, id, 'REF-ALONE');++ expect(await deleteReport(dir, id, createInFlightRegistry())).toEqual({ ok: true });+ expect(existsSync(sentMarkerPathForId(dir, id))).toBe(false);+ });++ test('the tombstone cap bounds marker-only records, oldest first', async () => {+ const dir = makeTmpDir();+ const total = MAX_SENT_TOMBSTONE_COUNT + 3;+ const ids: string[] = [];+ for (let i = 1; i <= total; i += 1) {+ const id = rid(i);+ ids.push(id);+ seedSentMarker(dir, id, `OK-${i}`, ridCreatedAt(i));+ }++ await runRetentionSweep(dir, createInFlightRegistry());++ expect(existsSync(sentMarkerPathForId(dir, nth(ids, 0)))).toBe(false);+ expect(existsSync(sentMarkerPathForId(dir, nth(ids, 2)))).toBe(false);+ expect(existsSync(sentMarkerPathForId(dir, nth(ids, -1)))).toBe(true);+ });++ test('boot reconciliation does not demote a report the marker says sent', async () => {+ const dir = makeTmpDir();+ // `markUploading` landed, the send succeeded, and the terminal write could+ // not touch the sidecar: it is stuck at `uploading` with the marker beside+ // it. Demoting would write a false `interrupted-by-restart` into a record+ // that ships inside the next diagnostic bundle.+ const id = await seedReport(dir, 1, { state: 'uploading', note: 'stuck mid-send' });+ seedSentMarker(dir, id, 'REF-BOOT');++ expect(await reconcileStaleUploading(dir)).toBe(0);+ expect((await readSidecarValue(sidecarPathForId(dir, id)))?.state).toBe('uploading');+ });++ // chmod is the only fixture that keeps a PARSEABLE note behind a read+ // failure, which is what makes this the end-to-end proof that recording the+ // send did not cost the note the skipped write exists to protect.+ test.skipIf(process.getuid?.() === 0 || process.platform === 'win32')(+ 'the reporter note survives an EACCES send that the marker records',+ async () => {+ const dir = makeTmpDir();+ const note = 'crashed while renaming a folder';+ const id = await seedReport(dir, 1, { state: 'generated', note });+ const path = sidecarPathForId(dir, id);+ chmodSync(path, 0o000);+ const store = createBugReportSidecarStore({ dir });++ await store.sendHooks.onSendResult(id, { kind: 'sent', reference: 'REF-EACCES-MARK' });++ const marked = existsSync(sentMarkerPathForId(dir, id));+ chmodSync(path, 0o644);+ expect(marked).toBe(true);+ expect((await readSidecarValue(path))?.note).toBe(note);+ },+ );+});++/**+ * The scan behind `listReports`, `runRetentionSweep` and+ * `reconcileStaleUploading` used to drop the read outcome silently, so an+ * engineer asking why a row is stuck degraded had no trace on the most common+ * path. It warns now — once per id, because the list is re-scanned on every+ * dialog open and every retention sweep.+ */+describe('scanReports diagnostics — an unreadable sidecar warns once, not once per scan', () => {+ test('the first scan names the id and the reason, later scans stay quiet', async () => {+ const dir = makeTmpDir();+ const id = await seedReport(dir, 1, { state: 'generated', note: 'a note' });+ writeFileSync(sidecarPathForId(dir, id), 'state: [unclosed\n bad: : :\n');+ const { logger, warns } = makeWarnRecorder();+ const store = createBugReportSidecarStore({ dir, logger });++ await store.list();+ const scanWarns = () =>+ warns.filter((w) => w.message.includes('sidecar unreadable during scan'));+ expect(scanWarns()).toHaveLength(1);+ expect(JSON.stringify(nth(scanWarns(), 0).data)).toContain('parse-error');+ expect(JSON.stringify(nth(scanWarns(), 0).data)).toContain(id);++ await store.list();+ await store.list();+ expect(scanWarns()).toHaveLength(1);+ });++ test('a sidecar that reads cleanly again re-arms the warning', async () => {+ const dir = makeTmpDir();+ const id = await seedReport(dir, 1, { state: 'generated' });+ const path = sidecarPathForId(dir, id);+ const healthy = readFileSync(path);+ writeFileSync(path, 'state: [unclosed\n bad: : :\n');+ const { logger, warns } = makeWarnRecorder();+ const store = createBugReportSidecarStore({ dir, logger });+ const scanWarns = () =>+ warns.filter((w) => w.message.includes('sidecar unreadable during scan'));++ await store.list();+ expect(scanWarns()).toHaveLength(1);++ writeFileSync(path, healthy);+ await store.list();+ writeFileSync(path, 'state: [unclosed\n bad: : :\n');+ await store.list();++ // A file that degrades a second time is a second event, not a repeat.+ expect(scanWarns()).toHaveLength(2);+ });++ test('the registry re-arms per reason and per file kind, and is bounded', () => {+ const warned = createSidecarScanWarnRegistry();+ const id = rid(1);++ expect(warned.shouldWarn(id, 'sidecar', 'parse-error')).toBe(true);+ expect(warned.shouldWarn(id, 'sidecar', 'parse-error')).toBe(false);+ // A file that degrades a DIFFERENT way is a different event.+ expect(warned.shouldWarn(id, 'sidecar', 'io-error')).toBe(true);+ // So is the OTHER file for the same report, and clearing one must not+ // re-arm the other: a report whose sidecar reads cleanly on every scan+ // would otherwise re-log its unreadable marker forever.+ expect(warned.shouldWarn(id, 'marker', 'unreadable')).toBe(true);+ warned.clear(id, 'sidecar');+ expect(warned.shouldWarn(id, 'sidecar', 'parse-error')).toBe(true);+ expect(warned.shouldWarn(id, 'marker', 'unreadable')).toBe(false);++ // The set is bounded: ids churn over a long-lived desktop process, so it+ // resets wholesale rather than growing forever.+ const other = createSidecarScanWarnRegistry();+ for (let i = 0; i <= MAX_REMEMBERED_SCAN_WARNINGS; i += 1) {+ other.shouldWarn(`${i}`, 'sidecar', 'parse-error');+ }+ expect(other.shouldWarn('0', 'sidecar', 'parse-error')).toBe(true);+ });++ test('an unreadable sent marker warns too, and says what was lost with it', async () => {+ const dir = makeTmpDir();+ const id = await seedReport(dir, 1, { state: 'generated' });+ writeFileSync(sentMarkerPathForId(dir, id), 'not: [yaml\n : :');+ const { logger, warns } = makeWarnRecorder();+ const store = createBugReportSidecarStore({ dir, logger });++ await store.list();+ await store.list();++ // Same trace an unreadable sidecar gets, and deduplicated the same way: the+ // row still reads `sent`, but with no reference Contact support disappears+ // and with no `sentAt` it sorts first into the tombstone cap.+ const markerWarns = warns.filter((w) => w.message.includes('sent marker unreadable'));+ expect(markerWarns).toHaveLength(1);+ expect(JSON.stringify(nth(markerWarns, 0).data)).toContain(id);+ });++ test('each unreadable sidecar warns on its own, not just the first one seen', async () => {+ const dir = makeTmpDir();+ const first = await seedReport(dir, 1, { state: 'generated' });+ const second = await seedReport(dir, 2, { state: 'generated' });+ writeFileSync(sidecarPathForId(dir, first), 'state: [unclosed\n : :');+ writeFileSync(sidecarPathForId(dir, second), 'state: [unclosed\n : :');+ const { logger, warns } = makeWarnRecorder();+ const store = createBugReportSidecarStore({ dir, logger });++ await store.list();++ const ids = warns+ .filter((w) => w.message.includes('sidecar unreadable during scan'))+ .map((w) => JSON.stringify(w.data));+ expect(ids).toHaveLength(2);+ expect(ids.some((d) => d.includes(first))).toBe(true);+ expect(ids.some((d) => d.includes(second))).toBe(true);+ });+});+describe('legacy zip mtime ordering', () => {test('a sidecar-less zip sorts by its file mtime', async () => {const dir = makeTmpDir();diff --git a/packages/desktop/src/main/bug-report-sidecar.ts b/packages/desktop/src/main/bug-report-sidecar.tsindex 9b3664b12..0edf329be 100644--- a/packages/desktop/src/main/bug-report-sidecar.ts+++ b/packages/desktop/src/main/bug-report-sidecar.ts@@ -30,6 +30,18 @@* reporter's own prose, and a transient EACCES must not be allowed to erase it.* Retention is the deliberate exception — it still unlinks an unreadable* sidecar whose bundle is already gone, and one evicted by the unsent caps.+ *+ * That refusal costs nothing for a failed send, which stays retryable either+ * way. For a CONFIRMED one it would: with nothing recording the send, the row+ * keeps offering Retry (a second upload of a bundle the intake already took),+ * has no reference to hand support, and never leaves the unsent pool, so the+ * cap eviction above eventually unlinks the note the refusal was protecting.+ * So a `sent` outcome the sidecar could not hold is written to a SIBLING+ * marker instead (`<base>-bugreport.sent.yaml`) — a new file, so nothing has to+ * be overwritten to record that the send happened. Its EXISTENCE is the record;+ * its contents only add the reference. Every reader here therefore checks the+ * marker before the sidecar's own `state`, and every path that removes a+ * report removes the marker with it.*/import { readdir, readFile, realpath, stat, unlink } from 'node:fs/promises';@@ -40,8 +52,12 @@ import {type OkBugReportDeleteResult,type OkBugReportListResult,type OkBugReportListRow,+ REPORT_SENT_MARKER_SCHEMA_VERSION,+ REPORT_SENT_MARKER_SUFFIX,REPORT_SIDECAR_SCHEMA_VERSION,type ReportBundleLevel,+ type ReportSentMarker,+ ReportSentMarkerSchema,type ReportSidecar,ReportSidecarSchema,type ReportSidecarState,@@ -90,6 +106,56 @@ export function createInFlightRegistry(): InFlightRegistry {};}+/**+ * Cap on remembered scan warnings. The live report set is bounded by the+ * retention caps, but ids churn over a long-lived desktop process, so the set+ * is cleared wholesale on overflow rather than growing forever — a coarse reset+ * that at worst re-logs one warning.+ */+export const MAX_REMEMBERED_SCAN_WARNINGS = 256;++/**+ * Remembers which unreadable sidecars have already been warned about during a+ * scan. The scan behind `listReports` runs on every history-dialog open and+ * every retention sweep, so an undeduplicated warning would bury the log in+ * repeats of one file — which is why the diagnostic was left out entirely+ * rather than added as a line change. Per store instance, not module scope, for+ * the same reason `InFlightRegistry` is: module state leaks between tests.+ */+export interface SidecarScanWarnRegistry {+ /** True the first time this report's `kind` file is seen unusable for this reason. */+ shouldWarn(id: string, kind: 'sidecar' | 'marker', reason: string): boolean;+ /**+ * Re-arm one report's warnings for ONE file kind, when that file reads+ * cleanly again — a second degradation is a second event. Scoped to the kind+ * because a report's two files fail independently: a sidecar recovering says+ * nothing about the marker beside it, and clearing both would re-log the+ * marker on every scan that read the sidecar.+ */+ clear(id: string, kind: 'sidecar' | 'marker'): void;+}++export function createSidecarScanWarnRegistry(): SidecarScanWarnRegistry {+ const seen = new Set<string>();+ // NUL cannot appear in a report id, a kind or a reason, so it cannot forge a key.+ const prefixFor = (id: string, kind: string): string => `${id}\u0000${kind}\u0000`;+ return {+ shouldWarn: (id, kind, reason) => {+ const key = `${prefixFor(id, kind)}${reason}`;+ if (seen.has(key)) return false;+ if (seen.size >= MAX_REMEMBERED_SCAN_WARNINGS) seen.clear();+ seen.add(key);+ return true;+ },+ clear: (id, kind) => {+ const prefix = prefixFor(id, kind);+ for (const key of seen) {+ if (key.startsWith(prefix)) seen.delete(key);+ }+ },+ };+}+/** The sidecar path for a report id (`<base>-bugreport.zip` → `<base>-bugreport.yaml`). */export function sidecarPathForId(dir: string, id: string): string {return join(dir, id.replace(/\.zip$/, '.yaml'));@@ -100,6 +166,14 @@ export function zipPathForId(dir: string, id: string): string {return join(dir, id);}+/**+ * The `sent`-marker path for a report id+ * (`<base>-bugreport.zip` → `<base>-bugreport.sent.yaml`).+ */+export function sentMarkerPathForId(dir: string, id: string): string {+ return join(dir, id.replace(/\.zip$/, REPORT_SENT_MARKER_SUFFIX));+}+/*** Serialize a validated sidecar to YAML and write it atomically. Mirrors* `skill-state`'s `parseDocument('')` + `createNode` + `toString()` (the raw@@ -122,6 +196,59 @@ export async function writeReportSidecar(dir: string, sidecar: ReportSidecar): Pawait atomicWriteFile(sidecarPathForId(dir, parsed.data.id), doc.toString());}+/**+ * Record a confirmed send in the sibling marker. Written ONLY when the sidecar+ * itself could not be made to say `sent` — the marker is the fallback record+ * for a file we must not rewrite, not a second copy of every send. Throws on a+ * genuine write failure; its one caller logs that.+ *+ * No `safeParse` before the write, unlike `writeReportSidecar` above. That one+ * validates because its input crosses a trust boundary — a sidecar read off+ * disk and then mutated. This one builds its document from two typed parameters+ * and a constant, so the shape below is already everything the schema would+ * check, and a runtime guard that cannot fire is noise rather than safety.+ */+async function writeSentMarker(+ dir: string,+ id: string,+ sentAt: string,+ reference: string,+): Promise<void> {+ // Every field REQUIRED here, unlike the reader's schema where all but+ // `version` are optional. The reader has to tolerate a half-written marker;+ // the writer dropping `reference` would ship one with no handle for support,+ // and nothing would fail. Naming the shape makes that a compile error.+ const marker: Required<Pick<ReportSentMarker, 'version' | 'id' | 'sentAt' | 'reference'>> = {+ version: REPORT_SENT_MARKER_SCHEMA_VERSION,+ id,+ sentAt,+ reference,+ };+ const doc = parseDocument('');+ doc.contents = doc.createNode(marker) as ParsedNode;+ await atomicWriteFile(sentMarkerPathForId(dir, id), doc.toString());+}++/**+ * Best-effort marker CONTENTS. `null` means "no detail", never "no marker": the+ * caller already knows from the directory listing that the file is there, and+ * that presence is the load-bearing fact. This only recovers the reference on+ * top of it, so every failure arm — absent, locked, unparseable, alias bomb —+ * collapses to `null` rather than being distinguished. Never throws, for the+ * same reason `readReportSidecar` does not: `scanReports` no longer wraps its+ * reads, so an escape here would take the whole history list with it.+ */+async function readSentMarkerDetail(markerPath: string): Promise<ReportSentMarker | null> {+ try {+ const doc = parseDocument(await readFile(markerPath, 'utf-8'));+ if (doc.errors.length > 0) return null;+ const parsed = ReportSentMarkerSchema.safeParse(doc.toJSON());+ return parsed.success ? parsed.data : null;+ } catch {+ return null;+ }+}+/*** Why a sidecar could be read but not used — diagnostic only; all three* preserve. Deliberately not exported: it is reachable through@@ -195,6 +322,16 @@ interface ScannedReport {sidecarRead: SidecarReadResult;/** A sidecar FILE was present (even if unreadable/corrupt). */sidecarPresent: boolean;+ /**+ * A `sent` marker FILE was present (even if unreadable). Its EXISTENCE is the+ * record that the intake accepted this bundle, so it outranks whatever the+ * sidecar's own `state` says — the marker is only ever written when that+ * sidecar could not be updated, so the two only disagree when the sidecar is+ * the stale one.+ */+ sentMarkerPresent: boolean;+ /** Marker contents when they parsed — the reference and the send time. */+ sentMarker: ReportSentMarker | null;zipExists: boolean;zipBytes: number;zipMtime: string | null;@@ -205,13 +342,27 @@ interface ScannedReport {* with or without a sidecar, and a tombstone sidecar whose zip is gone. Scoped* to the report basename shape so an unrelated file in the directory is ignored.*/-async function scanReports(dir: string): Promise<ScannedReport[]> {+async function scanReports(+ dir: string,+ logger?: SidecarLogger,+ warned?: SidecarScanWarnRegistry,+): Promise<ScannedReport[]> {const entries = await readdir(dir).catch(() => [] as string[]);const ids = new Set<string>();const sidecarIds = new Set<string>();+ const markerIds = new Set<string>();for (const entry of entries) {if (entry.endsWith('.zip') && isReportIdShape(entry)) {ids.add(entry);+ } else if (entry.endsWith(REPORT_SENT_MARKER_SUFFIX)) {+ // Tested BEFORE the plain `.yaml` arm, which a marker also matches:+ // stripping only `.yaml` would yield `<base>-bugreport.sent.zip`, which+ // is not a report id, so the marker would be silently dropped.+ const id = `${entry.slice(0, -REPORT_SENT_MARKER_SUFFIX.length)}.zip`;+ if (isReportIdShape(id)) {+ ids.add(id);+ markerIds.add(id);+ }} else if (entry.endsWith('.yaml')) {const id = entry.replace(/\.yaml$/, '.zip');if (isReportIdShape(id)) {@@ -230,12 +381,47 @@ async function scanReports(dir: string): Promise<ScannedReport[]> {const read = sidecarPresent? await readReportSidecar(sidecarPathForId(dir, id)): ({ kind: 'absent' } as const);+ // This scan backs the list, the retention sweep and boot reconciliation,+ // so it is the path an engineer asking "why is this row degraded?" hits+ // first. Warn once per id+reason: the send path already logs its own+ // refusal, but nothing spoke for the read that merely degraded a row.+ if (read.kind === 'unreadable') {+ if (warned === undefined || warned.shouldWarn(id, 'sidecar', read.reason)) {+ logger?.warn(+ { id, reason: read.reason, err: read.err },+ 'bug-report: sidecar unreadable during scan, row degraded',+ );+ }+ } else if (read.kind === 'ok') {+ warned?.clear(id, 'sidecar');+ }const sidecar = read.kind === 'ok' ? read.sidecar : null;+ const sentMarkerPresent = markerIds.has(id);+ const sentMarker = sentMarkerPresent+ ? await readSentMarkerDetail(sentMarkerPathForId(dir, id))+ : null;+ // A marker that is present but unusable costs more than it looks: the row+ // keeps `sent` (so no duplicate upload) but loses the reference, which+ // takes Contact support with it, and with no `sentAt` the record sorts to+ // the front of the tombstone cap that unlinks it. Same trace as an+ // unreadable sidecar gets, and deduplicated by the same registry.+ if (sentMarkerPresent && sentMarker === null) {+ if (warned === undefined || warned.shouldWarn(id, 'marker', 'unreadable')) {+ logger?.warn(+ { id },+ 'bug-report: sent marker unreadable during scan, send recorded without its reference',+ );+ }+ } else if (sentMarker !== null) {+ warned?.clear(id, 'marker');+ }return {id,sidecar,sidecarRead: read,sidecarPresent,+ sentMarkerPresent,+ sentMarker,zipExists: zipStat !== null,zipBytes: zipStat?.size ?? sidecar?.zipBytes ?? 0,zipMtime: zipStat?.mtime.toISOString() ?? null,@@ -252,21 +438,30 @@ function projectBundleLevel(raw: string | undefined): ReportBundleLevel | 'unkno/** Project a scanned report to the renderer-facing list row. */function toListRow(dir: string, scanned: ScannedReport): OkBugReportListRow {const s = scanned.sidecar;- // A sidecar file that was present but unreadable can't be trusted as+ // The `sent` marker outranks the sidecar's own state: it is only ever written+ // when that sidecar could not be updated, so it is the newer of the two. A+ // sidecar file that was present but unreadable can't be trusted as// `generated` — it renders as a degraded `unknown` row. A plain// sidecar-less legacy zip is a normal, retryable `generated` report.- const state: ReportSidecarState = s- ? normalizeReportSidecarState(s.state)- : scanned.sidecarPresent- ? 'unknown'- : scanned.zipExists- ? 'generated'- : 'unknown';+ const state: ReportSidecarState = scanned.sentMarkerPresent+ ? 'sent'+ : s+ ? normalizeReportSidecarState(s.state)+ : scanned.sidecarPresent+ ? 'unknown'+ : scanned.zipExists+ ? 'generated'+ : 'unknown';const degraded = (scanned.sidecarPresent && s === null) || state === 'unknown';const projectSlug = s?.projectSlug ?? null;+ // The marker carries the reference precisely when the sidecar could not, so+ // the row can still offer Contact support on a send it can prove happened.+ const reference = s?.reference ?? scanned.sentMarker?.reference;return {id: scanned.id,- createdAt: s?.createdAt ?? scanned.zipMtime ?? '',+ // A marker-only record has no other timestamp; its send time at least sorts+ // it sensibly rather than dumping it at the bottom of the list.+ createdAt: s?.createdAt ?? scanned.zipMtime ?? scanned.sentMarker?.sentAt ?? '',bundleLevel: projectBundleLevel(s?.bundleLevel),state,zipBytes: scanned.zipBytes,@@ -274,7 +469,7 @@ function toListRow(dir: string, scanned: ScannedReport): OkBugReportListRow {zipExists: scanned.zipExists,systemWide: s?.systemWide ?? projectSlug === null,projectSlug,- ...(s?.reference !== undefined ? { reference: s.reference } : {}),+ ...(reference !== undefined ? { reference } : {}),...(s?.lastError !== undefined ? { lastError: s.lastError } : {}),...(s?.note !== undefined ? { note: s.note } : {}),attemptsCount: s?.attempts?.length ?? 0,@@ -285,9 +480,13 @@ function toListRow(dir: string, scanned: ScannedReport): OkBugReportListRow {}/** List persisted reports, newest first. Never throws — a scan failure resolves to `{ ok: false }`. */-export async function listReports(dir: string): Promise<OkBugReportListResult> {+export async function listReports(+ dir: string,+ logger?: SidecarLogger,+ warned?: SidecarScanWarnRegistry,+): Promise<OkBugReportListResult> {try {- const scanned = await scanReports(dir);+ const scanned = await scanReports(dir, logger, warned);const reports = scanned.map((r) => toListRow(dir, r))// Newest first by createdAt; empty timestamps (unreadable, no zip mtime)@@ -350,6 +549,7 @@ export async function deleteReport(if (zipPath === null) return { ok: false, reason: 'id-invalid' };if (inFlight.has(id)) return { ok: false, reason: 'in-flight' };const sidecarPath = sidecarPathForId(dir, id);+ const markerPath = sentMarkerPathForId(dir, id);const zipExisted = await stat(zipPath).then(() => true,() => false,@@ -358,10 +558,17 @@ export async function deleteReport(() => true,() => false,);- if (!zipExisted && !sidecarExisted) return { ok: false, reason: 'not-found' };+ // A marker can outlive both: retention reclaims a corrupt sidecar whose+ // bundle is gone, and the send record beside it is then the whole report.+ const markerExisted = await stat(markerPath).then(+ () => true,+ () => false,+ );+ if (!zipExisted && !sidecarExisted && !markerExisted) return { ok: false, reason: 'not-found' };const zipOk = await unlinkIfPresent(zipPath);const sidecarOk = await unlinkIfPresent(sidecarPath);- return zipOk && sidecarOk ? { ok: true } : { ok: false, reason: 'io-error' };+ const markerOk = await unlinkIfPresent(markerPath);+ return zipOk && sidecarOk && markerOk ? { ok: true } : { ok: false, reason: 'io-error' };}/** Build a minimal `generated` sidecar for a report with no record at all (a retried legacy zip). */@@ -443,6 +650,9 @@ async function markUploading(* confirmed send). Never throws. The state write is SKIPPED when the existing* sidecar could not be read — the outcome is logged instead of overwriting a* record whose contents are unknown, so the report stays retryable.+ *+ * A `sent` outcome is the one case where "stays retryable" has a cost, so it+ * gets the sibling marker: see the write at the end of this function.*/async function recordSendResult(dir: string,@@ -450,8 +660,13 @@ async function recordSendResult(outcome: SidecarSendOutcome,inFlight: InFlightRegistry,logger?: SidecarLogger,+ warned?: SidecarScanWarnRegistry,): Promise<void> {const at = new Date().toISOString();+ // Whether the send's terminal state actually landed IN the sidecar. Set only+ // after a successful write, so a skipped write and a thrown one both fall+ // through to the marker below.+ let recorded = false;try {const base = await readSidecarForTransition(dir, id, logger);if (base === null) {@@ -460,7 +675,13 @@ async function recordSendResult(// reporter's only handle on the report with support, so losing it// silently is worse than the missed state write. The row keeps its// prior state, which leaves the report retryable rather than stranded.- logger?.warn({ id, outcome }, 'bug-report: send outcome not recorded, sidecar unreadable');+ // Scoped to the SIDECAR on purpose: a `sent` outcome still gets recorded,+ // in the marker written below, so a message claiming the outcome was lost+ // would send an engineer looking for a duplicate upload that is not there.+ logger?.warn(+ { id, outcome },+ 'bug-report: send outcome not written to the sidecar, it was unreadable',+ );} else {const attempt =outcome.kind === 'sent'@@ -494,13 +715,36 @@ async function recordSendResult(next = { ...next, state: 'email-drafted' };}await writeReportSidecar(dir, next);+ recorded = true;}} catch (err) {// `outcome` rides along for the same reason the `base === null` branch logs// it: on a `sent` whose write failed, this is the only surviving copy of// the reference.- logger?.warn({ id, err, outcome }, 'bug-report: failed to record send result');+ logger?.warn({ id, err, outcome }, 'bug-report: failed to write the send result sidecar');} finally {+ // A send the INTAKE CONFIRMED is a fact the store must not lose, and for+ // this one outcome the log is not enough. Left unrecorded, the row keeps+ // offering Retry — re-uploading a bundle the intake already took — hides the+ // reference support asks for, and never leaves the unsent pool, where the+ // cap eviction below eventually unlinks the zip AND the sidecar, destroying+ // the very note the skipped write exists to protect. The marker records the+ // send in a NEW file, so nothing has to be overwritten to say it happened.+ //+ // INSIDE the `finally`, ahead of the lock release, for the same reason the+ // sidecar write above sits inside the `try`: the in-flight lock is what+ // holds `deleteReport` and the retention eviction off this report, and the+ // marker is the send's only durable record on this path. Releasing first+ // leaves a window in which a delete arriving on the event loop sees no+ // marker, unlinks the zip and sidecar, and reports success — and then this+ // write lands, resurrecting the report the user just deleted as a phantom+ // `sent` tombstone. The `.catch` is what keeps a marker-write failure from+ // stranding the lock.+ if (outcome.kind === 'sent' && !recorded) {+ await writeSentMarker(dir, id, at, outcome.reference).catch((err: unknown) => {+ logger?.warn({ id, err, outcome }, 'bug-report: failed to write the sent marker');+ });+ }inFlight.delete(id);}// Retention runs after the terminal write so a just-`sent` report's zip is@@ -508,7 +752,7 @@ async function recordSendResult(// The sweep logs its own per-file failures and is documented never to throw,// so anything caught here is a contract violation — log it rather than// discarding it, or a sweep that stops running becomes undiagnosable.- await runRetentionSweep(dir, inFlight, logger).catch((err: unknown) => {+ await runRetentionSweep(dir, inFlight, logger, warned).catch((err: unknown) => {logger?.warn({ err }, 'bug-report: retention sweep failed unexpectedly');});}@@ -522,14 +766,20 @@ async function recordSendResult(export async function reconcileStaleUploading(dir: string,logger?: SidecarLogger,+ warned?: SidecarScanWarnRegistry,): Promise<number> {let reconciled = 0;try {- const scanned = await scanReports(dir);+ const scanned = await scanReports(dir, logger, warned);const at = new Date().toISOString();for (const report of scanned) {if (report.sidecar === null) continue;if (normalizeReportSidecarState(report.sidecar.state) !== 'uploading') continue;+ // A marker beside it says the send LANDED and only the terminal write+ // failed — not a crash mid-send. Demoting would stamp a false+ // `interrupted-by-restart` into a record that ships inside the next+ // diagnostic bundle and reads there as a failure that never happened.+ if (report.sentMarkerPresent) continue;const next: ReportSidecar = {...report.sidecar,state: 'upload-failed',@@ -564,48 +814,61 @@ export async function runRetentionSweep(dir: string,inFlight: InFlightRegistry,logger?: SidecarLogger,+ warned?: SidecarScanWarnRegistry,): Promise<void> {let scanned: ScannedReport[];try {- scanned = await scanReports(dir);+ scanned = await scanReports(dir, logger, warned);} catch (err) {logger?.warn({ err }, 'bug-report: retention scan failed');return;}+ // Mirrors `toListRow`'s projection, marker first for the same reason.const stateOf = (r: ScannedReport): ReportSidecarState =>- r.sidecar- ? normalizeReportSidecarState(r.sidecar.state)- : r.zipExists- ? 'generated'- : 'unknown';-- // Drop the zip on a confirmed send; keep the sidecar as a tombstone.+ r.sentMarkerPresent+ ? 'sent'+ : r.sidecar+ ? normalizeReportSidecarState(r.sidecar.state)+ : r.zipExists+ ? 'generated'+ : 'unknown';++ // Drop the zip on a confirmed send; keep the record as a tombstone.for (const r of scanned) {- if (stateOf(r) === 'sent' && r.zipExists && r.sidecar && !inFlight.has(r.id)) {- const removed = await unlinkIfPresent(zipPathForId(dir, r.id));- if (removed) {- r.zipExists = false;- await writeReportSidecar(dir, { ...r.sidecar, zipDeleted: true }).catch((err: unknown) => {- logger?.warn({ id: r.id, err }, 'bug-report: failed to tombstone a sent report');- });- }+ if (stateOf(r) !== 'sent' || !r.zipExists || inFlight.has(r.id)) continue;+ const removed = await unlinkIfPresent(zipPathForId(dir, r.id));+ if (!removed) continue;+ r.zipExists = false;+ // The `zipDeleted` stamp is a convenience — the row already falls back to+ // "no zip on disk". A send known only from its marker has no readable+ // sidecar to stamp, and writing one is exactly what this store refuses.+ if (r.sidecar) {+ await writeReportSidecar(dir, { ...r.sidecar, zipDeleted: true }).catch((err: unknown) => {+ logger?.warn({ id: r.id, err }, 'bug-report: failed to tombstone a sent report');+ });}}const sortByCreatedAtAsc = (a: ScannedReport, b: ScannedReport): number => {- const at = a.sidecar?.createdAt ?? a.zipMtime ?? '';- const bt = b.sidecar?.createdAt ?? b.zipMtime ?? '';+ // Send time is the last resort: a marker-only tombstone has no other+ // timestamp, and ordering every one of them as `''` would make the+ // oldest-first cap below evict by id instead of by age.+ const at = a.sidecar?.createdAt ?? a.zipMtime ?? a.sentMarker?.sentAt ?? '';+ const bt = b.sidecar?.createdAt ?? b.zipMtime ?? b.sentMarker?.sentAt ?? '';return at < bt ? -1 : at > bt ? 1 : a.id < b.id ? -1 : 1;};- // Sent-tombstone cap: oldest first, delete the sidecar (the zip is already gone).+ // Sent-tombstone cap: oldest first, delete the record (the zip is already+ // gone). Both files go — a marker left behind would be a `sent` row for a+ // report with nothing else to show, and would bypass the cap forever.const tombstones = scanned.filter((r) => stateOf(r) === 'sent' && !r.zipExists).sort(sortByCreatedAtAsc);const tombstoneOverflow = Math.max(0, tombstones.length - MAX_SENT_TOMBSTONE_COUNT);for (const tombstone of tombstones.slice(0, tombstoneOverflow)) {await unlinkIfPresent(sidecarPathForId(dir, tombstone.id));+ await unlinkIfPresent(sentMarkerPathForId(dir, tombstone.id));}// Orphan sweep: an unparseable sidecar whose zip is already gone belongs to@@ -622,10 +885,18 @@ export async function runRetentionSweep(// the reference and the reporter's note), so unlinking one that is merely// locked or momentarily unreadable would destroy the record outright — a// harder version of the overwrite this fix exists to prevent.+ //+ // A `sent` marker beside it takes it out of scope entirely: with the marker+ // the report IS a tombstone, so it belongs to the cap above and this sweep's+ // "belongs to neither cap" premise no longer holds. Skipping matters most+ // right after the zip is reclaimed a few lines up — without it, marking a+ // send would immediately expose the corrupt sidecar to this unlink and+ // destroy the reporter's note, which is the erasure the skipped write exists+ // to prevent.for (const r of scanned) {const durablyCorrupt =r.sidecarRead.kind === 'unreadable' && r.sidecarRead.reason !== 'io-error';- if (durablyCorrupt && !r.zipExists && !inFlight.has(r.id)) {+ if (durablyCorrupt && !r.zipExists && !r.sentMarkerPresent && !inFlight.has(r.id)) {await unlinkIfPresent(sidecarPathForId(dir, r.id));logger?.warn({@@ -687,6 +958,10 @@ export function createBugReportSidecarStore(opts: {}): BugReportSidecarStore {const { dir, logger } = opts;const inFlight = createInFlightRegistry();+ // One registry per store, shared by every scan the store runs, so a file that+ // is unreadable warns once across the list, the sweep and boot reconciliation+ // rather than once per each.+ const scanWarned = createSidecarScanWarnRegistry();return {async recordGenerated(meta) {const sidecar: ReportSidecar = {@@ -705,16 +980,17 @@ export function createBugReportSidecarStore(opts: {} catch (err) {logger?.warn({ id: sidecar.id, err }, 'bug-report: failed to write generated sidecar');}- await runRetentionSweep(dir, inFlight, logger).catch((err: unknown) => {+ await runRetentionSweep(dir, inFlight, logger, scanWarned).catch((err: unknown) => {logger?.warn({ err }, 'bug-report: retention sweep failed unexpectedly');});},sendHooks: {onSendStart: (id) => markUploading(dir, id, inFlight, logger),- onSendResult: (id, outcome) => recordSendResult(dir, id, outcome, inFlight, logger),+ onSendResult: (id, outcome) =>+ recordSendResult(dir, id, outcome, inFlight, logger, scanWarned),},- list: () => listReports(dir),+ list: () => listReports(dir, logger, scanWarned),remove: (id) => deleteReport(dir, id, inFlight),- reconcileStaleUploading: () => reconcileStaleUploading(dir, logger),+ reconcileStaleUploading: () => reconcileStaleUploading(dir, logger, scanWarned),};}diff --git a/packages/desktop/src/shared/ipc-channels.ts b/packages/desktop/src/shared/ipc-channels.tsindex 8dd668569..6b477783e 100644--- a/packages/desktop/src/shared/ipc-channels.ts+++ b/packages/desktop/src/shared/ipc-channels.ts@@ -971,8 +971,8 @@ export interface RequestChannels {* A crash invitation already carries the answer on its event.* - `{kind: 'list'}` → the persisted report history (newest first), read* from the per-report sidecars in `~/.ok/bug-reports/`.- * - `{kind: 'delete', id}` → remove a persisted report's zip + sidecar by- * `id`, containment-checked.+ * - `{kind: 'delete', id}` → remove a persisted report's zip, sidecar and+ * `sent` marker by `id`, containment-checked.* Later report operations widen this payload rather than adding channels.* Never throws — every failure mode is discriminated so the dialog can* render it; each preload method casts the union result to its own arm.