Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): collect ShipIt logs and install staging age (PRD-7852) (#3340)

Andrew Mikofalvy82fe99e501f6
diff --git a/.changeset/shipit-install-failure-evidence.md b/.changeset/shipit-install-failure-evidence.md
new file mode 100644
index 000000000..eeb8b5944
--- /dev/null
+++ b/.changeset/shipit-install-failure-evidence.md
@@ -0,0 +1,7 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Bug reports now carry the evidence needed to diagnose an update that fails to install. On macOS the actual swap of the app bundle is performed by a helper that runs after the app has already exited, so when an install silently fails there is no part of the app still running to notice. The app could tell you afterwards that the update did not install, but a report sent at that point contained nothing about why — the helper keeps its own log, and reports were not collecting it. Two failed-install reports in a row reached the same dead end.
+
+Reports now include that helper's log, so a failed install can be traced to the step it stopped at instead of guessing. Only the app's own log is collected, never those of other applications on the machine that use the same update mechanism. The bundle's privacy notice names the file whenever it is present, says the update helper wrote it rather than the app, and flags it as machine-wide rather than belonging to the project you reported from; the reference page listing everything the app writes to your disk now covers it too. The app also now records how long an update had been waiting when you asked to install it, and reports that number both when you click Relaunch and when a failed install is detected on the next launch — a timing correlation that previously could not be checked across reports at all.
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdx
index d1778e8ee..95d6ef194 100644
--- a/docs/content/reference/what-open-knowledge-writes.mdx
+++ b/docs/content/reference/what-open-knowledge-writes.mdx
@@ -37,6 +37,7 @@ The macOS app ships as a signed `.dmg` you drag into `/Applications`. On launch
| `~/.ok/logs/desktop.<date>.log` | Desktop app + renderer log | Outside-project (home dir) |
| `~/.ok/mcp-status.json` | Records your first-launch MCP-setup consent choice | Outside-project (home dir) |
| `~/Library/Caches/OpenKnowledge-updater/` | Staged auto-update downloads (electron-updater) | Outside-project (home dir) |
+| `~/Library/Caches/com.inkeep.open-knowledge.ShipIt/` | Install log of the macOS update helper (Squirrel's ShipIt), which swaps the app bundle after the app has quit. The only record of why an update failed to install, so a bug report you send collects it — only this app's, never those of other applications that use the same update mechanism | Outside-project (home dir) |
| `~/Library/Application Support/OpenKnowledge/Crashpad/` | Native crash minidumps, written by the OS crash handler (Electron's Crashpad) if the app ever crashes. Local-only: the crash reporter runs with `uploadToServer: false`, so no dump is ever uploaded automatically | Outside-project (home dir) |
| `~/Library/Application Support/OpenKnowledge/bug-report-dirty-shutdown.json` | Dirty-shutdown sentinel — written on **every** launch, refreshed as it runs, and removed on a clean quit. The next launch reads it to tell an app crash (prompts you) from the machine ending the session — a reboot, an OS shutdown, or dying asleep (suppressed and logged instead) | Outside-project (home dir) |
| `~/Library/Application Support/OpenKnowledge/bug-report-crash-acks.json` | Records which crash-report invitations you already answered or dismissed, so the same crash never re-prompts | Outside-project (home dir) |
@@ -280,7 +281,7 @@ None of your content, by default. Everything above is written to your own disk.
| What | When | Where it goes |
| --- | --- | --- |
| Diagnostic bundle | Only when you run `ok diagnose bundle` (you can inspect it first) | Wherever you send it |
-| In-app bug report | Only when you click **Send** in the desktop app's **Help → Report a bug…** dialog — it builds a secret-redacted zip you can reveal and inspect first, and nothing is sent without that explicit click. After a crash, the same dialog adds an **off-by-default** "Include crash dump" checkbox: a crash dump is a memory snapshot that can contain document content and can't be redacted, and it is only ever attached when you check that box | By default, Send makes no network request — it opens a prefilled email draft to [email protected] that you send yourself, naming the zip to attach. Only when an operator has configured a bug-report intake endpoint ([`OK_BUG_REPORT_INTAKE_URL`](./configuration.mdx#environment-variables)) does Send upload the zip there, falling back to the same email draft if the upload fails |
+| In-app bug report | Only when you click **Send** in the desktop app's **Help → Report a bug…** dialog — it builds a secret-redacted zip you can reveal and inspect first, and nothing is sent without that explicit click. After a crash, the same dialog adds an **off-by-default** "Include crash dump" checkbox: a crash dump is a memory snapshot that can contain document content and can't be redacted, and it is only ever attached when you check that box. On macOS the zip also carries the update helper's install log (listed above), which is machine-wide rather than project-scoped; the zip's own README names it and says where it came from | By default, Send makes no network request — it opens a prefilled email draft to [email protected] that you send yourself, naming the zip to attach. Only when an operator has configured a bug-report intake endpoint ([`OK_BUG_REPORT_INTAKE_URL`](./configuration.mdx#environment-variables)) does Send upload the zip there, falling back to the same email draft if the upload fails |
| Uninstall feedback | Only after an uninstall has already succeeded, and only if you pick a reason, type a note, or give an email address on the optional "Before you go" screen (desktop app) or prompt (`ok uninstall`). Skipping it, `--yes`, `--json`, and any non-interactive run send nothing | `openknowledge.ai/api/feedback` — the reason you picked, your note, your email address if you gave one, plus the app version and platform. It files one ticket for the team; nothing from your notes is included |
| Semantic search embeddings | Only when you enable [semantic search](./configuration.mdx#semantic-search) **and** set a key — off by default | Your configured embeddings provider (OpenAI by default) |
| GitHub sync / share | When you sync, clone, publish, or share | GitHub |
diff --git a/packages/cli/src/commands/bug-report-bundle.test.ts b/packages/cli/src/commands/bug-report-bundle.test.ts
index 74916d29e..1e5500278 100644
--- a/packages/cli/src/commands/bug-report-bundle.test.ts
+++ b/packages/cli/src/commands/bug-report-bundle.test.ts
@@ -11,8 +11,10 @@ import { basename, dirname, join, resolve } from 'node:path';
import { afterEach, describe, expect, test } from 'vitest';
import {
type BundleLogger,
+ collectShipItLogFiles,
collectStandardBundle,
collectUserLogFiles,
+ DESKTOP_BUNDLE_ID,
defaultBugReportZipPath,
okBugReportsDir,
} from './bug-report-bundle.ts';
@@ -461,6 +463,155 @@ describe('collectUserLogFiles — shared collector', () => {
});
});
+describe('collectShipItLogFiles — Squirrel.Mac install logs', () => {
+ // ShipIt swaps the bundle after the app exits, so its own log is the only
+ // artifact that records why an install did not take. Without it a bundle can
+ // report the failure but never explain it.
+ test('collects the desktop app ShipIt logs', () => {
+ const cachesDir = makeTmpDir();
+ writeAt(cachesDir, `${DESKTOP_BUNDLE_ID}.ShipIt/ShipIt_stderr.log`, 'Installation failed\n');
+ writeAt(cachesDir, `${DESKTOP_BUNDLE_ID}.ShipIt/ShipIt_stdout.log`, '');
+
+ const names = collectShipItLogFiles(cachesDir)
+ .map((f) => basename(f))
+ .sort();
+
+ expect(names).toEqual(['ShipIt_stderr.log', 'ShipIt_stdout.log']);
+ });
+
+ // Every Squirrel app on the machine keeps its install history in a sibling
+ // directory. A `*.ShipIt` glob would forward unrelated software's update
+ // history to support, so the match must be anchored to our own bundle id.
+ test('never harvests another application ShipIt logs', () => {
+ const cachesDir = makeTmpDir();
+ writeAt(cachesDir, `${DESKTOP_BUNDLE_ID}.ShipIt/ShipIt_stderr.log`, 'ours\n');
+ writeAt(cachesDir, 'com.tinyspeck.slackmacgap.ShipIt/ShipIt_stderr.log', 'theirs\n');
+ writeAt(cachesDir, 'com.anthropic.claudefordesktop.ShipIt/ShipIt_stderr.log', 'theirs\n');
+
+ const bodies = collectShipItLogFiles(cachesDir).map((f) => readFileSync(f, 'utf8'));
+
+ expect(bodies).toEqual(['ours\n']);
+ });
+
+ // `userLogFiles` stages by basename alone, so a sub-bundle id whose dir also
+ // holds a `ShipIt_stderr.log` would collide with the app's own in the zip.
+ // Exact-match keeps one writer per staged name.
+ test('ignores sub-bundle ShipIt directories that would collide when staged', () => {
+ const cachesDir = makeTmpDir();
+ writeAt(cachesDir, `${DESKTOP_BUNDLE_ID}.ShipIt/ShipIt_stderr.log`, 'app\n');
+ writeAt(cachesDir, `${DESKTOP_BUNDLE_ID}.server.ShipIt/ShipIt_stderr.log`, 'server\n');
+
+ const bodies = collectShipItLogFiles(cachesDir).map((f) => readFileSync(f, 'utf8'));
+
+ expect(bodies).toEqual(['app\n']);
+ });
+
+ // Non-macOS hosts have no such directory at all; collection is a no-op there
+ // rather than a platform branch at every call site.
+ test('returns empty when the caches directory does not exist', () => {
+ expect(collectShipItLogFiles(join(makeTmpDir(), 'absent'))).toEqual([]);
+ });
+
+ // The collector existing is not the deliverable — reaching the zip is. This
+ // is the assertion a triager's experience actually depends on.
+ test('stages the ShipIt log into the bundle under logs/', async () => {
+ const userLogsDir = makeTmpDir();
+ const cachesDir = makeTmpDir();
+ writeFileSync(join(userLogsDir, 'desktop.2026-08-05.log'), DESKTOP_LOG_LINE);
+ writeAt(
+ cachesDir,
+ `${DESKTOP_BUNDLE_ID}.ShipIt/ShipIt_stderr.log`,
+ 'ShipIt[1:2] Installation completed successfully\n',
+ );
+ const outputPath = join(makeTmpDir(), 'report.zip');
+
+ const { zipPath } = await collectStandardBundle({
+ projectDir: makeProjectDir('bundle-proj'),
+ redact: true,
+ outputPath,
+ userLogsDir,
+ shipItLogFiles: collectShipItLogFiles(cachesDir),
+ });
+
+ expect(listZipEntries(zipPath)).toContain('logs/ShipIt_stderr.log');
+ });
+
+ // ShipIt logs record every app-bundle swap on the machine, so a
+ // project-scoped bundle carrying them is no longer project-scoped. The
+ // recipient has to be told — but in its own paragraph: the daily-rotation
+ // sentence that describes the user-wide app logs is not true of an installer
+ // log, so filing it there would disclose it under a false description.
+ test('discloses the ShipIt log in its own paragraph, not the daily user-wide list', async () => {
+ const userLogsDir = makeTmpDir();
+ const cachesDir = makeTmpDir();
+ writeFileSync(join(userLogsDir, 'cli.2026-08-05.log'), CLI_LOG_MATCHING_SLUG);
+ writeFileSync(join(userLogsDir, 'desktop.2026-08-05.log'), DESKTOP_LOG_LINE);
+ writeAt(cachesDir, `${DESKTOP_BUNDLE_ID}.ShipIt/ShipIt_stderr.log`, 'swap\n');
+ const outputPath = join(makeTmpDir(), 'report.zip');
+
+ const { zipPath } = await collectStandardBundle({
+ projectDir: makeProjectDir('bundle-proj'),
+ redact: true,
+ outputPath,
+ userLogsDir,
+ shipItLogFiles: collectShipItLogFiles(cachesDir),
+ });
+
+ // Scoped to the Privacy section: the Contents list names every file, so a
+ // whole-README assertion would pass whatever the notes actually said.
+ const readme = readZipEntry(zipPath, 'README.md');
+ const privacy = readme.slice(readme.indexOf('## Privacy'));
+ const scopeNote = privacy.slice(
+ privacy.indexOf('Scope: some collected logs'),
+ privacy.indexOf('Installer logs:'),
+ );
+ expect(scopeNote).toContain('- logs/desktop.2026-08-05.log');
+ expect(scopeNote).not.toContain('ShipIt');
+
+ expect(privacy).toContain('macOS update helper');
+ expect(privacy.match(/^- logs\/ShipIt_stderr\.log$/gm)).toHaveLength(1);
+ });
+
+ // The scope note is deliberately silent on an unscoped bundle — nothing was
+ // narrowed, so there is no narrower reading to correct. What the installer
+ // log needs disclosed is not its scope but what it is, so that disclosure
+ // cannot ride on the scope note: the unscoped bundle is the one most likely
+ // to be attached to a public issue under "safe to attach".
+ test('discloses the installer log in an unscoped bundle too', async () => {
+ const cachesDir = makeTmpDir();
+ writeAt(cachesDir, `${DESKTOP_BUNDLE_ID}.ShipIt/ShipIt_stderr.log`, 'swap\n');
+ const outputPath = join(makeTmpDir(), 'report.zip');
+
+ const { zipPath } = await collectStandardBundle({
+ redact: true,
+ outputPath,
+ userLogsDir: makeTmpDir(),
+ shipItLogFiles: collectShipItLogFiles(cachesDir),
+ });
+
+ const readme = readZipEntry(zipPath, 'README.md');
+ expect(readme).toContain('Project: (unscoped)');
+ expect(readme).toContain('macOS update helper');
+ expect(readme).toContain('- logs/ShipIt_stderr.log');
+ });
+
+ // The disclosure names files; a bundle with no installer log must not claim
+ // one is present.
+ test('omits the installer disclosure when no ShipIt log was collected', async () => {
+ const outputPath = join(makeTmpDir(), 'report.zip');
+
+ const { zipPath } = await collectStandardBundle({
+ projectDir: makeProjectDir('bundle-proj'),
+ redact: true,
+ outputPath,
+ userLogsDir: makeTmpDir(),
+ shipItLogFiles: collectShipItLogFiles(join(makeTmpDir(), 'absent')),
+ });
+
+ expect(readZipEntry(zipPath, 'README.md')).not.toContain('macOS update helper');
+ });
+});
+
describe('collectStandardBundle — narrowing diagnostics', () => {
test('counts only the taggable logs the slug ruled out', async () => {
const userLogsDir = makeTmpDir();
diff --git a/packages/cli/src/commands/bug-report-bundle.ts b/packages/cli/src/commands/bug-report-bundle.ts
index 8d99bb03b..3658d1569 100644
--- a/packages/cli/src/commands/bug-report-bundle.ts
+++ b/packages/cli/src/commands/bug-report-bundle.ts
@@ -26,6 +26,7 @@ import type { ZipFile } from 'yazl';
// too, so a value import in either direction would form a runtime cycle.
import type { DesktopMetadata } from '../diagnose/bundle.ts';
import { redactContent, SECRET_PATTERN_NAMES } from './bug-report-redact.ts';
+import { DESKTOP_BUNDLE_ID } from './desktop-dispatch.ts';
/**
* Where `ok bug-report` (and the desktop report flow) write bundles by
@@ -79,6 +80,13 @@ export interface CollectStandardBundleOptions {
outputPath: string;
/** Override the user-level logs directory (defaults to `~/.ok/logs`). */
userLogsDir?: string;
+ /**
+ * Squirrel.Mac ShipIt install logs, already resolved by the caller (see
+ * `collectShipItLogFiles`). Passed in rather than resolved here so this
+ * collector keeps no implicit dependency on the real home directory — the
+ * same reason `userLogsDir` is injectable, but enforced by construction.
+ */
+ shipItLogFiles?: string[];
/** User note added as `note.txt`, scrubbed like any content file when `redact` is on. */
note?: string;
/** Extra files (e.g. an opted-in crash minidump) added under `extra/`. */
@@ -214,6 +222,49 @@ export function collectUserLogFiles(projectSlug: string | null, logsDir: string)
return collectLogs(projectSlug, logsDir).files;
}
+/**
+ * The one desktop-identity constant, re-exported so ShipIt-log collection and
+ * `open -b` dispatch can never drift apart. Its own drift guard against
+ * `electron-builder.yml`'s `appId` lives beside the declaration.
+ */
+export { DESKTOP_BUNDLE_ID };
+
+/**
+ * The two text logs Squirrel.Mac's ShipIt writes into its per-bundle cache
+ * dir. `ShipItState.plist` sits beside them but is a binary plist — staging it
+ * through the text scrub would garble it, and the swap narrative lives in
+ * stderr regardless.
+ */
+const SHIPIT_LOG_FILES = ['ShipIt_stderr.log', 'ShipIt_stdout.log'] as const;
+
+/**
+ * Squirrel.Mac's own install logs (`~/Library/Caches/<bundleId>.ShipIt/`).
+ *
+ * ShipIt performs the bundle swap AFTER the app has exited, so no OK process
+ * is alive to witness a failed install. The updater's boot-time detector can
+ * report THAT an install did not take but never why — these logs are the only
+ * artifact carrying ShipIt's own reason (the per-step move narration, the
+ * NSError domain/code it aborted on, and its exit status).
+ *
+ * Matched on the exact bundle id rather than a `*.ShipIt` glob: every other
+ * Squirrel app on the machine keeps its install history in a sibling directory,
+ * and harvesting those would leak unrelated software's update history into a
+ * bundle the user forwards to support. Exactness also makes a stale bundle id
+ * fail safe — it degrades to "no ShipIt logs collected", never to another
+ * app's logs being harvested.
+ *
+ * macOS-only by construction — on other platforms the caches dir does not
+ * exist and this returns empty rather than special-casing the platform.
+ */
+export function collectShipItLogFiles(
+ cachesDir: string,
+ bundleId: string = DESKTOP_BUNDLE_ID,
+): string[] {
+ const shipItDir = join(cachesDir, `${bundleId}.ShipIt`);
+ if (!existsSync(shipItDir)) return [];
+ return SHIPIT_LOG_FILES.map((name) => join(shipItDir, name)).filter((p) => existsSync(p));
+}
+
function collectLogs(
projectSlug: string | null,
logsDir: string,
@@ -355,6 +406,10 @@ export async function collectStandardBundle(
const { files: localSinkFiles } = opts.projectDir
? collectLocalSinkLogs(opts.projectDir)
: { files: [] };
+ // Not project-scoped: ShipIt updates the whole app bundle, so its logs are
+ // host-level evidence regardless of which project the report came from. The
+ // scope disclosure below reports them as user-wide for exactly that reason.
+ const shipItFiles = opts.shipItLogFiles ?? [];
logger?.info(
{
@@ -364,6 +419,7 @@ export async function collectStandardBundle(
logFilesExcludedByProjectSlug,
lockFileCount: lockFiles.length,
localSinkFileCount: localSinkFiles.length,
+ shipItLogFileCount: shipItFiles.length,
},
'files collected',
);
@@ -376,7 +432,7 @@ export async function collectStandardBundle(
addContentFiles({
zipfile,
- files: logFiles,
+ files: [...logFiles, ...shipItFiles],
prefix: 'logs',
redact,
bundleFiles,
@@ -448,6 +504,16 @@ export async function collectStandardBundle(
const totalRedacted = redactions.reduce((sum, r) => sum + r.lineCount, 0);
+ // Disclosed independently of project scope, because the thing to disclose is
+ // not scope. These are not the app's own logs at all — they are written by
+ // the macOS update helper that swaps the app bundle after the app has
+ // exited, so an unscoped bundle (where the scope note below correctly stays
+ // silent) would otherwise ship a category of data the README never names.
+ // Intersected with what was actually written, so a file that turned out to
+ // be unreadable is not disclosed as present.
+ const shipItEntryNames = new Set(shipItFiles.map((f) => `logs/${basename(f)}`));
+ const installerLogEntries = bundleFiles.filter((f) => shipItEntryNames.has(f));
+
// The families the slug cannot narrow are per-machine, per-day singletons, so
// a project-scoped bundle still carries whatever else the machine was doing
// that day. Secret scrubbing does not narrow this — it matches credentials,
@@ -456,8 +522,13 @@ export async function collectStandardBundle(
// Only meaningful against a declared project scope: an unscoped bundle
// narrows nothing and is user-wide throughout, so there is no narrower
// reading for the note to correct.
+ // Installer logs are held out and disclosed above instead: they are not
+ // per-day singletons, and listing them here would file them under a sentence
+ // that is not true of them.
const userWideLogEntries = projectSlug
- ? bundleFiles.filter((f) => f.startsWith('logs/') && !isProjectTaggable(f))
+ ? bundleFiles.filter(
+ (f) => f.startsWith('logs/') && !isProjectTaggable(f) && !shipItEntryNames.has(f),
+ )
: [];
const readme = [
@@ -483,6 +554,17 @@ export async function collectStandardBundle(
'',
]
: []),
+ ...(installerLogEntries.length > 0
+ ? [
+ 'Installer logs: written by the macOS update helper rather than by',
+ 'OpenKnowledge itself, and machine-wide rather than scoped to any one',
+ 'project. They record the install and update history of this app on',
+ 'this machine. Only this app is collected, never other applications',
+ 'that use the same update mechanism:',
+ ...installerLogEntries.map((f) => `- ${f}`),
+ '',
+ ]
+ : []),
...(redact
? [
'This bundle was auto-redacted before packaging.',
diff --git a/packages/cli/src/report-bundle.test.ts b/packages/cli/src/report-bundle.test.ts
index 20544f71c..b68912151 100644
--- a/packages/cli/src/report-bundle.test.ts
+++ b/packages/cli/src/report-bundle.test.ts
@@ -272,6 +272,33 @@ describe('collectReportBundle — standard level', () => {
expect(summary.systemWide).toBe(true);
expect(summary.projectSlug).toBeNull();
});
+
+ // The collector is tested directly beside `collectShipItLogFiles`, but this
+ // entry is where the caches dir is actually resolved and handed to it — the
+ // seam a triager's bundle depends on, and the one a refactor can drop
+ // without any collector test noticing.
+ test('resolves the ShipIt install log from the caches dir and stages it under logs/', async () => {
+ const cachesDir = makeTmpDir();
+ writeAt(
+ cachesDir,
+ 'com.inkeep.open-knowledge.ShipIt/ShipIt_stderr.log',
+ 'ShipIt: Failed to move bundle\n',
+ );
+ const outputPath = join(makeTmpDir(), 'report.zip');
+
+ const { zipPath, summary } = await collectReportBundle({
+ level: 'standard',
+ projectDir: makeStandardProjectDir(),
+ redact: true,
+ outputPath,
+ userLogsDir: makeTmpDir(),
+ cachesDir,
+ });
+
+ expect(listZipEntries(zipPath)).toContain('logs/ShipIt_stderr.log');
+ expect(summary.files).toContain('logs/ShipIt_stderr.log');
+ expect(readZipEntry(zipPath, 'logs/ShipIt_stderr.log')).toContain('Failed to move bundle');
+ });
});
describe('collectReportBundle — full level', () => {
@@ -338,6 +365,34 @@ describe('collectReportBundle — full level', () => {
expect(body).not.toContain(SECRET);
});
+ // The full level assembles through `diagnose/bundle.ts` rather than the
+ // standard collector, so its ShipIt wiring is a second seam that can break
+ // on its own. Directory name spelled out rather than imported from
+ // `DESKTOP_BUNDLE_ID`, so this also pins the path macOS actually writes.
+ test('carries the ShipIt install log the standard level collects', async () => {
+ const cachesDir = makeTmpDir();
+ writeAt(
+ cachesDir,
+ 'com.inkeep.open-knowledge.ShipIt/ShipIt_stderr.log',
+ `ShipIt: Failed to move bundle\ntoken ${SECRET}\n`,
+ );
+ const outputPath = join(makeTmpDir(), 'report.zip');
+
+ const { zipPath } = await collectReportBundle({
+ level: 'full',
+ projectDir: makeFullProjectDir(),
+ redact: true,
+ outputPath,
+ userLogsDir: makeTmpDir(),
+ cachesDir,
+ });
+
+ expect(listZipEntries(zipPath)).toContain('logs/ShipIt_stderr.log');
+ const shipIt = readZipEntry(zipPath, 'logs/ShipIt_stderr.log');
+ expect(shipIt).toContain('Failed to move bundle');
+ expect(shipIt).not.toContain(SECRET);
+ });
+
test('scrubs ROTATED user logs too, whose counter suffix defeats an extension test', async () => {
const projectDir = makeFullProjectDir();
const userLogsDir = makeTmpDir();
diff --git a/packages/cli/src/report-bundle.ts b/packages/cli/src/report-bundle.ts
index f480595b7..d0b31f667 100644
--- a/packages/cli/src/report-bundle.ts
+++ b/packages/cli/src/report-bundle.ts
@@ -16,6 +16,7 @@ import { parse as parseYaml } from 'yaml';
import {
type BundleExtraFile,
type BundleLogger,
+ collectShipItLogFiles,
collectStandardBundle,
collectUserLogFiles,
resolveProjectSlug,
@@ -53,6 +54,8 @@ export interface CollectReportBundleOptions {
extraFiles?: BundleExtraFile[];
/** Override the user-level logs directory (standard-level test seam). */
userLogsDir?: string;
+ /** Override the macOS caches directory searched for ShipIt install logs (test seam). */
+ cachesDir?: string;
/**
* Collection-progress + warning sink. The full level reports its inventory
* via the manifest and uses this only for warnings (e.g. an opted-in extra
@@ -121,10 +124,12 @@ async function collectFullBundle(
// the same user-level logs. Omitting them silently dropped the renderer
// console from every desktop crash report, since the Electron main process
// captures it here rather than into the project's server sink.
- userLogFiles: collectUserLogFiles(
- projectSlug,
- opts.userLogsDir ?? join(homedir(), '.ok', 'logs'),
- ),
+ userLogFiles: [
+ ...collectUserLogFiles(projectSlug, opts.userLogsDir ?? join(homedir(), '.ok', 'logs')),
+ // Squirrel.Mac's install log. Not project-scoped — ShipIt swaps the whole
+ // app bundle, and it is the only record of why a post-exit install failed.
+ ...collectShipItLogFiles(opts.cachesDir ?? join(homedir(), 'Library', 'Caches')),
+ ],
deps: { readDesktopEnv, logger: opts.logger },
});
try {
@@ -181,6 +186,7 @@ export async function collectReportBundle(
redact: opts.redact,
outputPath: opts.outputPath,
userLogsDir: opts.userLogsDir,
+ shipItLogFiles: collectShipItLogFiles(opts.cachesDir ?? join(homedir(), 'Library', 'Caches')),
logger: opts.logger,
note: opts.note,
extraFiles: opts.extraFiles,
diff --git a/packages/desktop/src/main/auto-updater.ts b/packages/desktop/src/main/auto-updater.ts
index a454ae0e0..1fda7b199 100644
--- a/packages/desktop/src/main/auto-updater.ts
+++ b/packages/desktop/src/main/auto-updater.ts
@@ -1243,6 +1243,20 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa
// fallback can build its command on the next boot, before the
// launch check re-validates the cache (see the AppState field doc).
stagedInstallerPath,
+ // Staged-at for the pending version. This is the only moment the
+ // staging clock can start: `update-downloaded` is when Squirrel has
+ // the bundle and the install becomes requestable.
+ versionPendingInstallStagedAt: now().getTime(),
+ // The age is measured from the staged-at above, so the two move
+ // together: arming restarts the staging clock, which leaves any age
+ // recorded against the previous staging meaningless. Left set, it
+ // would be reported at the NEXT boot-detected failure as if it
+ // described that install — a stale number reads as real signal and
+ // is worse than the age being absent. Unlike
+ // `attemptedInstallSurfacedCount`, which is scoped to the version
+ // and so survives a same-version re-arm, this is scoped to the
+ // staging and resets with it.
+ attemptedInstallStagingAgeMs: null,
...(installCommittedAtDownload
? {
attemptedInstall: version,
@@ -1436,11 +1450,25 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa
// (install-on-quit is off there, so `onUpdateDownloaded` deliberately did
// not arm it — see that handler). Same fresh-budget semantics as the
// download-time arming on the other platforms.
+
+ // How long the update had been staged when the user asked for it. Recorded
+ // here because this is the last moment a live process knows it: the install
+ // happens after the quit, and the boot that detects a failure runs in a
+ // different process. `versionPendingInstallStagedAt` deliberately survives
+ // this persist — a Retry after a failed install measures from the original
+ // staging, which is what "how long has this been staged" means.
+ // A non-positive delta means the wall clock moved backwards between staging
+ // and the click (an NTP correction, a VM resume), not an instant install —
+ // report it as unknown, matching the read-side coercion in `parseAppState`.
+ const stagedAt = snapshot.versionPendingInstallStagedAt;
+ const rawStagingAge = stagedAt === null ? null : now().getTime() - stagedAt;
+ const stagingAgeMs = rawStagingAge !== null && rawStagingAge > 0 ? rawStagingAge : null;
if (
!persistSafely(
{
...snapshot,
versionPendingInstall: null,
+ attemptedInstallStagingAgeMs: stagingAgeMs,
...(platform === 'linux'
? {
attemptedInstall: pending,
@@ -1482,7 +1510,10 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa
});
}
}
- logger.info('relaunch-now invoked — calling autoUpdater.quitAndInstall', { pending });
+ logger.info('relaunch-now invoked — calling autoUpdater.quitAndInstall', {
+ pending,
+ stagingAgeMs,
+ });
onDispatch?.('relaunch-now');
// Arm the in-flight gate BEFORE the call, not after it returns. On
// Squirrel.Mac failures surface asynchronously (the `error` event, or a
@@ -1568,7 +1599,12 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa
// a genuinely-pending update armed rather than dropping it on garbage.
if (state.versionPendingInstall && versionAtLeast(currentVersion, state.versionPendingInstall)) {
const cleared = state.versionPendingInstall;
- const next = { ...state, versionPendingInstall: null, stagedInstallerPath: null };
+ const next = {
+ ...state,
+ versionPendingInstall: null,
+ stagedInstallerPath: null,
+ versionPendingInstallStagedAt: null,
+ };
if (persistSafely(next, 'stale-pending-cleared')) {
state = next;
logger.info('cleared stale versionPendingInstall — running has caught up', {
@@ -1601,7 +1637,16 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa
// Running reached the attempted version → install succeeded. Clear the
// record; the "Updated to Version ..." notice (Toast B, below) handles
// the success surface.
- const next = { ...state, attemptedInstall: null, attemptedInstallSurfacedCount: 0 };
+ // The age describes `attemptedInstall`; clearing one without the other
+ // leaves `state.json` self-contradictory for the triage read the whole
+ // record exists to serve. Same pairing as the cross-channel and give-up
+ // branches below.
+ const next = {
+ ...state,
+ attemptedInstall: null,
+ attemptedInstallSurfacedCount: 0,
+ attemptedInstallStagingAgeMs: null,
+ };
if (persistSafely(next, 'attempted-install-reconciled')) {
state = next;
onDispatch?.('attempted-install-reconciled');
@@ -1638,6 +1683,8 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa
attemptedInstallSurfacedCount: 0,
versionPendingInstall: null,
stagedInstallerPath: null,
+ versionPendingInstallStagedAt: null,
+ attemptedInstallStagingAgeMs: null,
};
if (persistSafely(next, 'attempted-install-cross-channel')) {
state = next;
@@ -1668,6 +1715,8 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa
attemptedInstallSurfacedCount: 0,
versionPendingInstall: null,
stagedInstallerPath: null,
+ versionPendingInstallStagedAt: null,
+ attemptedInstallStagingAgeMs: null,
};
if (persistSafely(next, 'install-failed-giveup')) {
state = next;
@@ -1703,6 +1752,10 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa
attempted,
running: currentVersion,
surfaced: next.attemptedInstallSurfacedCount,
+ // Null when the install was committed by a plain quit rather than a
+ // "Relaunch now" click — there is no request moment to measure to,
+ // and a zero here would read as an instant install.
+ stagingAgeMs: state.attemptedInstallStagingAgeMs,
});
// Reuse the relaunch-failed channel: both mean "a committed update did
// not install". The boot-detected case carries a `downloadUrl` so the
diff --git a/packages/desktop/src/main/state-store.ts b/packages/desktop/src/main/state-store.ts
index 1a1b7dd62..888da2441 100644
--- a/packages/desktop/src/main/state-store.ts
+++ b/packages/desktop/src/main/state-store.ts
@@ -189,6 +189,28 @@ export interface AppState {
* Non-negative integer.
*/
attemptedInstallSurfacedCount: number;
+ /**
+ * Epoch ms at which the pending version was staged. Rewritten by every
+ * `update-downloaded` that arms (a re-fire for the already-pending version
+ * dedupes out before reaching it), so it always describes the most recently
+ * staged artifact rather than the first one seen for that version.
+ *
+ * Deliberately NOT cleared when `relaunch-now` clears `versionPendingInstall`:
+ * a failed install leaves the same artifact staged, and a Retry should measure
+ * from when that artifact was originally staged, not from the retry.
+ */
+ versionPendingInstallStagedAt: number | null;
+ /**
+ * How long `attemptedInstall` had been staged when the install was actually
+ * requested, in ms. Recorded at "Relaunch now" and read on the NEXT boot,
+ * where the failed-install detector runs in a different process than the
+ * install it is reporting on — the age cannot be recomputed there, so it has
+ * to cross the quit as persisted state.
+ *
+ * Null when no explicit relaunch happened (the install-on-quit path commits
+ * without a click, so there is no request moment to measure to).
+ */
+ attemptedInstallStagingAgeMs: number | null;
/**
* Last version the app successfully booted under — compared to
* `app.getVersion()` at auto-updater start to decide whether to fire
@@ -310,6 +332,11 @@ export interface AppState {
const RECENT_CAP = 20;
const RECENT_FILES_CAP = 20;
+/** Epoch-ms / duration coercion shared by the additive updater timing fields. */
+function nonNegativeIntOrNull(value: unknown): number | null {
+ return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null;
+}
+
export function emptyState(): AppState {
return {
recentProjects: [],
@@ -319,6 +346,8 @@ export function emptyState(): AppState {
stagedInstallerPath: null,
attemptedInstall: null,
attemptedInstallSurfacedCount: 0,
+ versionPendingInstallStagedAt: null,
+ attemptedInstallStagingAgeMs: null,
lastSeenVersion: null,
lastSuccessfulCheckAt: null,
stuckHintShown: false,
@@ -841,6 +870,12 @@ export function parseAppState(raw: unknown): AppState | null {
obj.attemptedInstallSurfacedCount >= 0
? obj.attemptedInstallSurfacedCount
: 0;
+ // Additive timing fields. Both are diagnostic-only: a missing or corrupt
+ // value coerces to null, which reads downstream as "unknown" and never as a
+ // misleading zero. Negatives are rejected — a clock moving backwards between
+ // staging and the install request cannot produce a real age.
+ const versionPendingInstallStagedAt = nonNegativeIntOrNull(obj.versionPendingInstallStagedAt);
+ const attemptedInstallStagingAgeMs = nonNegativeIntOrNull(obj.attemptedInstallStagingAgeMs);
const lastSeenVersion = typeof obj.lastSeenVersion === 'string' ? obj.lastSeenVersion : null;
const lastSuccessfulCheckAt =
typeof obj.lastSuccessfulCheckAt === 'string' ? obj.lastSuccessfulCheckAt : null;
@@ -883,6 +918,8 @@ export function parseAppState(raw: unknown): AppState | null {
stagedInstallerPath,
attemptedInstall,
attemptedInstallSurfacedCount,
+ versionPendingInstallStagedAt,
+ attemptedInstallStagingAgeMs,
lastSeenVersion,
lastSuccessfulCheckAt,
stuckHintShown,
diff --git a/packages/desktop/tests/integration/auto-updater.test.ts b/packages/desktop/tests/integration/auto-updater.test.ts
index 2c45642a6..b898b0d75 100644
--- a/packages/desktop/tests/integration/auto-updater.test.ts
+++ b/packages/desktop/tests/integration/auto-updater.test.ts
@@ -641,6 +641,127 @@ describe('startAutoUpdater — initial configuration (parent §8.10 LOCKED)', ()
});
});
+// ————————————————————————————————————————————————————————
+// Staging age
+// ————————————————————————————————————————————————————————
+//
+// ShipIt performs the swap after the app exits, so when an install silently
+// fails no live process saw it and the bundle carries no ShipIt-side reason.
+// How long the update had been staged when the install was requested is the
+// one correlate the app CAN record, and it only becomes comparable across
+// reports if every install request emits it.
+
+describe('staging age — how long the update sat before the install was requested', () => {
+ test('records the staged-at moment when a version is armed', () => {
+ const { rig } = makeRig({ platform: 'darwin' });
+ rig.now = new Date('2026-04-21T12:00:00.000Z');
+ rig.updater.emit('update-downloaded', { version: '0.3.2' });
+ expect(rig.state.versionPendingInstallStagedAt).toBe(Date.parse('2026-04-21T12:00:00.000Z'));
+ });
+
+ test('relaunch-now records the staging age and logs it', () => {
+ const { rig } = makeRig({ platform: 'darwin' });
+ rig.now = new Date('2026-04-21T12:00:00.000Z');
+ rig.updater.emit('update-downloaded', { version: '0.3.2' });
+ // A couple of seconds: the reported shape is a click landing moments after
+ // a newer build re-staged underneath an already-open notification.
+ rig.now = new Date('2026-04-21T12:00:02.060Z');
+ rig.ipc.invoke('ok:update:relaunch-now');
+
+ expect(rig.state.attemptedInstallStagingAgeMs).toBe(2060);
+ expect(rig.logger.info).toHaveBeenCalledWith(
+ 'relaunch-now invoked — calling autoUpdater.quitAndInstall',
+ expect.objectContaining({ stagingAgeMs: 2060 }),
+ );
+ // The click clears the banner gate but must leave the staged-at stamp
+ // alone: the artifact is still staged, so a Retry after a failed install
+ // measures from the original staging rather than restarting the clock.
+ expect(rig.state.versionPendingInstall).toBeNull();
+ expect(rig.state.versionPendingInstallStagedAt).toBe(Date.parse('2026-04-21T12:00:00.000Z'));
+ });
+
+ // `Date.now()` is wall-clock, not monotonic. An NTP correction between
+ // staging and the click makes the delta negative, and there is no age to
+ // report — same "unknown" the no-click path yields, not an instant install.
+ test('reports null rather than zero when the clock moved backwards while staged', () => {
+ const { rig } = makeRig({ platform: 'darwin' });
+ rig.now = new Date('2026-04-21T12:00:00.000Z');
+ rig.updater.emit('update-downloaded', { version: '0.3.2' });
+ rig.now = new Date('2026-04-21T11:59:57.000Z');
+ rig.ipc.invoke('ok:update:relaunch-now');
+
+ expect(rig.state.attemptedInstallStagingAgeMs).toBeNull();
+ });
+
+ // The failed-install detector runs on the NEXT boot, in a different process
+ // than the install it reports. Without the persisted age the one number that
+ // could corroborate a timing hypothesis dies with the process that had it.
+ test('the boot-time failure notice reports the age persisted before the quit', () => {
+ const { rig } = makeRig({
+ attemptedInstall: '0.16.0-beta.3',
+ appVersion: '0.16.0-beta.1',
+ attemptedInstallStagingAgeMs: 2060,
+ });
+ expect(rig.logger.warn).toHaveBeenCalledWith(
+ 'attempted install did not take — surfacing failure notice',
+ expect.objectContaining({ stagingAgeMs: 2060 }),
+ );
+ });
+
+ // Install-on-quit commits without a click, so there is no request moment to
+ // measure to. Null says "unknown"; a zero would read as "installed instantly
+ // after staging" and corroborate exactly the hypothesis it cannot speak to.
+ test('reports null rather than zero when no relaunch click preceded the failure', () => {
+ const { rig } = makeRig({
+ attemptedInstall: '0.16.0-beta.3',
+ appVersion: '0.16.0-beta.1',
+ });
+ expect(rig.logger.warn).toHaveBeenCalledWith(
+ 'attempted install did not take — surfacing failure notice',
+ expect.objectContaining({ stagingAgeMs: null }),
+ );
+ });
+
+ // An age belongs to the version whose install it was recorded for. Arming a
+ // NEW version starts a fresh measurement, so a leftover age from an earlier
+ // click must not travel with it — a stale non-null number reads as real
+ // signal to a triager and is worse than the age simply being absent.
+ test('a newly armed version does not inherit an earlier version staging age', () => {
+ const { rig: session } = makeRig({ platform: 'darwin' });
+ session.now = new Date('2026-04-21T12:00:00.000Z');
+ session.updater.emit('update-downloaded', { version: '0.3.2' });
+ session.now = new Date('2026-04-21T12:00:02.060Z');
+ session.ipc.invoke('ok:update:relaunch-now');
+ expect(session.state.attemptedInstallStagingAgeMs).toBe(2060);
+
+ // A newer build lands and is committed by a plain quit — no click, so the
+ // install of 0.3.3 has no request moment of its own.
+ session.now = new Date('2026-04-21T13:00:00.000Z');
+ session.updater.emit('update-downloaded', { version: '0.3.3' });
+ expect(session.state.attemptedInstall).toBe('0.3.3');
+
+ // 0.3.3 never took: the next boot is still on the old version.
+ const { rig: nextBoot } = makeRig({ ...session.state });
+ expect(nextBoot.logger.warn).toHaveBeenCalledWith(
+ 'attempted install did not take — surfacing failure notice',
+ expect.objectContaining({ attempted: '0.3.3', stagingAgeMs: null }),
+ );
+ });
+
+ // Once the install is reconciled as successful the age describes nothing —
+ // leaving it set makes `state.json` self-contradictory for the triage read
+ // the whole record exists to serve.
+ test('a reconciled successful install leaves no staging age behind', () => {
+ const { rig } = makeRig({
+ appVersion: '0.3.1',
+ attemptedInstall: '0.3.1',
+ attemptedInstallStagingAgeMs: 2060,
+ });
+ expect(rig.state.attemptedInstall).toBeNull();
+ expect(rig.state.attemptedInstallStagingAgeMs).toBeNull();
+ });
+});
+
// ————————————————————————————————————————————————————————
// Cross-channel veto on update-available
// ————————————————————————————————————————————————————————
diff --git a/packages/desktop/tests/unit/state-store-channel-fields.test.ts b/packages/desktop/tests/unit/state-store-channel-fields.test.ts
index dc16731cb..c41092b2a 100644
--- a/packages/desktop/tests/unit/state-store-channel-fields.test.ts
+++ b/packages/desktop/tests/unit/state-store-channel-fields.test.ts
@@ -95,6 +95,47 @@ describe('parseAppState — legacy updateChannel tolerance', () => {
});
});
+describe('parseAppState — updater staging-age fields', () => {
+ test('defaults both timing fields to null on a fresh state', () => {
+ expect(emptyState().versionPendingInstallStagedAt).toBeNull();
+ expect(emptyState().attemptedInstallStagingAgeMs).toBeNull();
+ });
+
+ test('a state.json predating the fields parses cleanly with nulls', () => {
+ const parsed = parseAppState({ recentProjects: [], lastOpenedProject: null });
+ expect(parsed?.versionPendingInstallStagedAt).toBeNull();
+ expect(parsed?.attemptedInstallStagingAgeMs).toBeNull();
+ });
+
+ test('preserves persisted values', () => {
+ const parsed = parseAppState({
+ recentProjects: [],
+ lastOpenedProject: null,
+ versionPendingInstallStagedAt: 1776772800000,
+ attemptedInstallStagingAgeMs: 2060,
+ });
+ expect(parsed?.versionPendingInstallStagedAt).toBe(1776772800000);
+ expect(parsed?.attemptedInstallStagingAgeMs).toBe(2060);
+ });
+
+ // These are diagnostic-only fields. A corrupt value must read as "unknown"
+ // rather than as a small age, which would look like a real measurement and
+ // corroborate a timing hypothesis nothing actually observed.
+ test.each([
+ ['a negative age', -1],
+ ['a non-integer', 12.5],
+ ['a string', '2060'],
+ ['null', null],
+ ])('coerces %s to null rather than a plausible-looking number', (_label, value) => {
+ const parsed = parseAppState({
+ recentProjects: [],
+ lastOpenedProject: null,
+ attemptedInstallStagingAgeMs: value,
+ });
+ expect(parsed?.attemptedInstallStagingAgeMs).toBeNull();
+ });
+});
+
describe('evaluateSchemaCompatibility — boot-time refuse-downgrade gate', () => {
test('returns ok when schemaVersion equals max supported (today)', () => {
const result = evaluateSchemaCompatibility(