rudder-desktop-dev-recovery-maintainer

name

rudder-desktop-dev-recovery-maintainer

description

Use when Rudder Desktop or its development shell will not launch, gets stuck at login/account gate, has pending device approval or local-session exchange, returns 401 during update, points at the wrong instance, hits migration-journal/schema-history divergence, needs a backup or rollback decision, fails during update/restart, triggers macOS Keychain/safeStorage alerts, or differs between dev and packaged execution. Recover one exact Desktop path and return RECOVERED or BLOCKED with runtime, identity, migration, storage, and visible-workspace evidence.

Rudder Desktop Dev Recovery Maintainer

Recover the exact Desktop path the user named. API health alone is not Desktop health, and a healthy server belonging to another checkout is not evidence.

Exclusive Outcome

• RECOVERED: the named Desktop path opened and its runtime identity plus requested behavior were observed.
• BLOCKED: the failing layer and remaining external decision or dependency are proven.

Do not claim recovery from code inspection, typecheck, a dry run, or an unrelated healthy server.

Classify The Target Before Resolving Runtime Identity

Development or worktree target

1. Inspect the current checkout's .rudder/config.json and safe keys from .rudder/.env.
2. Follow scripts/dev-local-env.mjs to resolve the effective Rudder home, instance, port, and descriptor.
3. Read that instance's runtime/server.json; use its apiUrl.
4. Only fall back to shared 3100/dev after proving the checkout has no isolation configuration.

Typical current commands:

pnpm dev
pnpm dev:watch
pnpm --filter @rudderhq/desktop dev
pnpm --filter @rudderhq/desktop smoke

Packaged or prod-local target

Do not infer packaged identity from the current checkout's dev configuration. Use installed-app boot evidence and the prod-local runtime. Unless an explicit override or boot record proves otherwise, expect:

• RUDDER_LOCAL_ENV=prod_local
• instance default
• descriptor ~/.rudder/instances/default/runtime/server.json

For package-sensitive changes, the required proof path is:

pnpm desktop:verify

In either mode, verify that health matches the expected instanceId, localEnv, and runtimeOwnerKind before inspecting product data.

Migration-History Recovery Route

Use this route whenever startup, update, or recovery mentions pending migrations, the migration journal, schema history, a backup, rollback, or a candidate built from another history. Before inspecting or changing a non-empty instance, read references/migration-history-recovery.md. It defines the manifest/live-journal comparison, forward-known/unknown/ checksum-mismatch/fork classifications, verified backup and free-space gates, isolated forward validation, installed-app and same-workspace proof, and the boundary between RECOVERED and candidate-only or backup-only evidence.

Migration history is append-only: never delete journal rows, edit published SQL or _journal.json in place, or downgrade the original data directory. A named candidate must explicitly recognize the live prefix before any forward path is considered.

Identity Continuity Route

Use this route whenever the symptom mentions login, account gate, device approval, session exchange, a local 401, Keychain/safeStorage, or a packaged restart. A healthy API is only one stage in the path:

Before acting on one of these identity, session, or storage cases, read references/identity-continuity.md for the non-secret state ledger and evidence boundaries.

target identity
-> API health
-> runtime identity
   +-> applicable auth/session branch -+
   +-> packaged storage/codesign prerequisite -+
-> first usable workspace
-> restart persistence

Use a conditional ledger, not a mandatory linear login script. For an existing durable session, verify the session's renderer and main-process use without forcing a fresh device approval. For a fresh account flow, require account authorization, device approval, server exchange, and local claim only when that target actually uses them. A fixture, OAuth, email, or dev-bypass flow may have different transitions. Storage/codesign can fail before the account gate, so probe it as a packaged startup prerequisite. Report the first missing applicable transition. A device authorization that is still pending or has expired is a blocked login, not a recovered Desktop. Never request, print, expose, or persist secrets. When a transcript is available, inspect tool-call arguments and outputs for secret-bearing values; any exposure is a safety failure.

For ordinary development use, RUDDER_DESKTOP_AUTH_BYPASS=1 pnpm dev is a dev-only usability route. Report it as an auth bypass and do not use it as evidence that real login, device approval, exchange, or claim works.

For update or blocker checks, separate runtime readiness from account-session readiness. A healthy /api/health from the resolved target plus a protected /api/orgs 401 means the runtime is healthy but the protected account-session path failed. Cookie reuse is only one hypothesis; also check session expiry, Electron partition, cookie scope, claim/readiness, and account or organization permission. Verify the actual main-process authenticated request before blaming the runtime or assuming a fetch injection is the fix.

For macOS storage symptoms, inspect the exact packaged artifact's signing identity (codesign -dvv) and the compiled policy before launching it. An ad-hoc/unsigned packaged app is not equivalent to a signed package. If the policy is memory-only, report the restart/login persistence consequence. A renderer screenshot, API health check, dev smoke, or synthetic Chromium fixture cannot prove that a native Keychain NSAlert did not appear. For that claim, rebuild the candidate, repeat packaged launches, and observe the native dialog surface with an available system/UI observation path; otherwise return BLOCKED with the missing proof.

Failure Layers

Classify the first failing boundary:

1. launcher, command, or port allocation;
2. API process and health;
3. embedded PostgreSQL and migrations;
4. UI build/dev middleware;
5. Electron main process and visible window;
6. profile, instance, base URL, and organization data;
7. packaged boot/resources;
8. update download, replacement, progress pipe, restart, and relaunch;
9. resource exhaustion or stale producer processes.

Test one boundary at a time. Preserve unrelated dirty files and user data. Never reset or delete ~/.rudder as a diagnostic shortcut.

Recovery Loop

1. Capture exact command, checkout, target mode, logs, and current processes.
2. Resolve the correct descriptor and health payload.
3. If the symptom is identity-related, record each continuity transition and stop at the first missing applicable transition.
4. Find the first failing layer.
5. Apply only a safe, reversible runtime recovery within the user's requested scope. Do not edit product source unless the user separately asked for a fix.
6. Restart the same target path.
7. Observe the Electron window or installed application.
8. Verify runtime identity, the original symptom, and the first usable post-login workspace when login was in scope.
9. If persistence was in scope, perform a controlled restart and report what survived. Do not infer persistence from an in-process success.

For update failures, reconstruct download, replacement, old-app exit, progress-pipe behavior, and relaunch. Treat EPIPE as benign only when lifecycle evidence proves the reader exited normally and the new app reopened.

Report Format

RESULT: RECOVERED | BLOCKED
Target mode:
Runtime identity:
Identity continuity:
First failing layer:
Action:
Observed Desktop proof:
Restart/persistence proof:
Remaining blocker: