feat: add Relay doctor diagnostics

README.md

@@ -2,6 +2,8 @@
 
 Safe installed setup is documented in [setup and configuration](docs/setup-and-configuration.md). Use an explicit absolute `--config-file` and preview before `--apply`; generic MCP is snippet-only.
 
+Use [`relay doctor`](docs/doctor.md) or `relay doctor --output json` to inspect an installed environment. Doctor is non-destructive; warning-only reports exit `0`, failures exit `1`, and invalid command usage exits `2`.
+
 For Linux-only Claude Desktop MCPB evaluation, see [the MCPB guide](integrations/claude-desktop/README.md) and [verification record](docs/claude-desktop-mcpb-verification.md).
 
 **Testing Relay for the first time?** Follow the [source-checkout installation and usage guide](docs/source-checkout-guide.md) to clone, run, connect an AI client, and complete a safe smoke test.

assets/compatibility.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "minimumPackageVersion": "0.1.0",
+  "mcpContractSchemaVersion": 1,
+  "migrationManifestVersion": 1,
+  "migrationCount": 4,
+  "skillMetadataVersion": 1,
+  "integrationTemplateVersion": 1
+}

docs/doctor.md

@@ -0,0 +1,86 @@
+# Relay doctor
+
+`relay doctor` inspects an installed Relay package without repairing it. The
+default output is human-readable; `relay doctor --output json` writes one
+schema-versioned JSON document for automation and support.
+
+Exit codes are stable:
+
+- `0`: no check failed. Warnings and skipped checks are allowed.
+- `1`: at least one diagnostic check failed.
+- `2`: the command or output option is invalid.
+
+The report schema is version `1` and always contains these checks, in order:
+
+1. `runtime.version`
+2. `runtime.platform`
+3. `package.assets`
+4. `paths.resolution`
+5. `paths.access`
+6. `database.state`
+7. `database.integrity`
+8. `database.native-addon`
+9. `integrations.codex`
+10. `integrations.claude-code`
+11. `integrations.generic-mcp`
+12. `compatibility.assets`
+13. `mcp.handshake`
+14. `ui.loopback`
+
+Each check is `healthy`, `warning`, `failure`, or `skipped` and includes a
+stable code. Human output uses `[OK]`, `[WARN]`, `[FAIL]`, and `[SKIP]`.
+
+## Safety boundaries
+
+Doctor does not migrate, repair, replace, truncate, or delete the configured
+database. It opens an existing database read-only, checks its migration
+ledger, and runs SQLite `quick_check` without exposing SQL or engine details.
+It does not edit client configuration or Relay ownership metadata and does
+not scan for unowned Codex, Claude Code, or generic MCP files. Only paths
+approved by the distribution contract may appear in output.
+
+MCP and UI probes run the installed command with a disposable temporary root,
+an absolute temporary database, bounded output, deterministic timeouts, and
+cleanup on success, failure, timeout, or interruption. No telemetry or remote
+support bundle is produced.
+
+## Troubleshooting stable codes
+
+- `runtime.version.*`, `runtime.platform.*`: use Node 24.x on a claimed
+  Windows x64, macOS arm64, or Linux x64/glibc runtime.
+- `package.assets.*`, `compatibility.assets.*`: reinstall the package from a
+  complete tarball; do not copy source-checkout files into an installation.
+- `paths.resolution.*`, `paths.access.*`: run `relay setup` with the intended
+  isolated paths and check directory permissions.
+- `database.missing`: initialize the installation with `relay setup`.
+- `database.pending-migrations`, `database.unknown-migrations`, or
+  `database.integrity-*`: preserve a backup and investigate the installation
+  or migration history; doctor does not perform recovery.
+- `database.native-addon-load-failed`: reinstall dependencies/package for the
+  supported Node ABI and platform.
+- `integrations.*`: inspect only the explicitly recorded ownership path and
+  use `relay setup --client ... --config-file <absolute-path>` when an entry
+  needs to be re-established.
+- `mcp.*` and `ui.*`: retry from the installed package, confirm the package
+  assets are complete, and check that loopback startup is permitted.
+
+## Human verification matrix
+
+Run each case against an isolated installed tarball, recording status/code,
+exit code, database/config bytes and mtimes, temporary roots, child processes,
+and whether any secret fixture value appeared:
+
+1. healthy setup;
+2. warning-only setup with no owned client integration;
+3. unsupported Node/platform simulation;
+4. missing immutable asset;
+5. unwritable mutable path;
+6. pending and corrupt database copies;
+7. invalid Codex and Claude owned entries;
+8. MCP timeout;
+9. UI startup failure;
+10. Ctrl+C during MCP and UI probes.
+
+The configured database, ownership metadata, and client files must remain
+byte-for-byte unchanged in every case. Temporary roots and child processes
+must be gone before doctor exits.

docs/setup-and-configuration.md

@@ -1,5 +1,10 @@
 # Safe setup and agent configuration
 
+After installation, run [`relay doctor`](doctor.md) from an arbitrary working
+directory to inspect runtime, assets, paths, database state, owned client
+entries, and isolated MCP/UI startup. Doctor never mutates the configured
+database or client files; see the human verification matrix in that guide.
+
 `relay setup` initializes Relay's data and configuration roots and opens the canonical database runtime so forward migrations run. It never replaces, resets, or deletes an existing database. Re-running it is safe.
 
 Mutable client setup is preview-first: it mutates only when `--apply` is supplied.

docs/superpowers/plans/2026-08-04-issue-42-relay-doctor-diagnostics.md

@@ -623,8 +623,15 @@ export interface DoctorCommand {
 }
 
 export function parseDoctorCommand(argv: readonly string[]): DoctorCommand;
-export function writeDoctorReport(stream: { write(text: string): unknown }, report: DoctorReport, output: DoctorCommand['output']): void;
-export async function runDoctorCommand(argv: readonly string[], dependencies: DoctorCommandDependencies): Promise<number>;
+export function writeDoctorReport(
+  stream: { write(text: string): unknown },
+  report: DoctorReport,
+  output: DoctorCommand['output'],
+): void;
+export async function runDoctorCommand(
+  argv: readonly string[],
+  dependencies: DoctorCommandDependencies,
+): Promise<number>;
 ```
 
 - [ ] **Step 1: Write failing parser/dispatcher tests.**

package.json

@@ -16,6 +16,7 @@
   "homepage": "https://github.com/krishna916/relay#readme",
   "files": [
     "dist/",
+    "assets/compatibility.json",
     "assets/migrations/",
     "skills/",
     "integrations/",

scripts/package/package-files.ts

@@ -3,6 +3,7 @@ export const REQUIRED_MIGRATION_PATHS: readonly string[] = [
   'package/assets/migrations/0002_tasks.sql',
   'package/assets/migrations/0003_task_session_id.sql',
   'package/assets/migrations/0004_task_normalized_title.sql',
+  'package/assets/compatibility.json',
 ];
 
 export const REQUIRED_PACKAGE_PATHS: readonly string[] = [

scripts/package/smoke-installed-package.ts

@@ -317,6 +317,55 @@ export async function verifyInstalledPackage(rootDir = process.cwd()): Promise<v
         );
     }
 
+    const doctorJson = runCli(
+      commandPath,
+      unrelatedCwd,
+      databasePath,
+      ['doctor', '--output', 'json'],
+      setupEnvironment,
+    );
+    if (doctorJson.status !== 0 || doctorJson.stderr !== '')
+      throw new Error(`Installed doctor JSON failed: ${doctorJson.stderr}`);
+    const doctorReport = JSON.parse(doctorJson.stdout) as {
+      schemaVersion?: number;
+      checks?: Array<{ id?: string }>;
+    };
+    if (
+      doctorReport.schemaVersion !== 1 ||
+      JSON.stringify(doctorReport.checks?.map((check) => check.id)) !==
+        JSON.stringify([
+          'runtime.version',
+          'runtime.platform',
+          'package.assets',
+          'paths.resolution',
+          'paths.access',
+          'database.state',
+          'database.integrity',
+          'database.native-addon',
+          'integrations.codex',
+          'integrations.claude-code',
+          'integrations.generic-mcp',
+          'compatibility.assets',
+          'mcp.handshake',
+          'ui.loopback',
+        ])
+    ) {
+      throw new Error('Installed doctor JSON did not return the stable 14-check contract.');
+    }
+    const doctorHuman = runCli(
+      commandPath,
+      unrelatedCwd,
+      databasePath,
+      ['doctor'],
+      setupEnvironment,
+    );
+    if (
+      doctorHuman.status !== 0 ||
+      doctorHuman.stderr !== '' ||
+      !doctorHuman.stdout.includes('Doctor summary:')
+    )
+      throw new Error(`Installed doctor human output failed: ${doctorHuman.stderr}`);
+
     const capture = runCli(commandPath, unrelatedCwd, databasePath, [
       'task',
       'capture',

scripts/package/stage-package-assets.ts

@@ -25,6 +25,7 @@ export async function stagePackageAssets(options: StagePackageAssetsOptions = {}
   const rootDir = resolve(options.rootDir ?? process.cwd());
   await copyMigrations(rootDir);
   for (const required of [
+    'assets/compatibility.json',
     'dist/web/index.html',
     'skills/relay-capture/SKILL.md',
     'integrations/generic-mcp/README.md',

scripts/validate-repository-assets.ts

@@ -37,6 +37,7 @@ export const requiredDistributionAssets = [
   'tests/fixtures/distribution/config-examples/claude-code-conflict.json',
   'tests/fixtures/distribution/lifecycle-policy.json',
   'tests/fixtures/distribution/version-compatibility.json',
+  'assets/compatibility.json',
   'tests/fixtures/setup/codex/empty.toml',
   'tests/fixtures/setup/codex/unrelated.toml',
   'tests/fixtures/setup/codex/matching.toml',
@@ -189,6 +190,21 @@ function validatePlaceholders(files: readonly string[]): void {
   }
 }
 
+function validateDoctorFixtures(files: readonly string[]): void {
+  const disallowed = [
+    /(?:[A-Za-z]:[\\/]|\/(?:Users|home|private|var)\/)/i,
+    /(?:bearer|api[_-]?key|access[_-]?token|private[_-]?key|secret)/i,
+    /(?:BEGIN [A-Z ]+ PRIVATE KEY|sk-[A-Za-z0-9_-]{10,})/,
+  ];
+  for (const filePath of files) {
+    if (!filePath.replaceAll('\\', '/').includes('tests/fixtures/doctor/')) continue;
+    const content = readFileSync(filePath, 'utf-8');
+    for (const pattern of disallowed) {
+      if (pattern.test(content)) fail(`Unsafe doctor fixture content found in ${filePath}`);
+    }
+  }
+}
+
 function asRecord(value: unknown, label: string): Record<string, unknown> {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     fail(`${label} must contain a JSON object.`);
@@ -526,6 +542,7 @@ export function validateRepositoryAssets(options: ValidateRepositoryAssetsOption
 
   validateJsonFiles(allFiles);
   validatePlaceholders(allFiles);
+  validateDoctorFixtures(allFiles);
   validateMarkdownLinks(
     join(rootDir, 'README.md'),
     readFileSync(join(rootDir, 'README.md'), 'utf-8'),

src/database/migration.ts

@@ -11,11 +11,25 @@ export interface MigrationFile {
   readonly checksum: string;
 }
 
+export interface MigrationManifestEntry {
+  readonly version: number;
+  readonly name: string;
+  readonly filename: string;
+}
+
 export function computeChecksum(content: string): string {
   return createHash('sha256').update(content, 'utf-8').digest('hex');
 }
 
 export function loadMigrationFiles(migrationsDir: string): readonly MigrationFile[] {
+  const manifest = loadMigrationManifest(migrationsDir);
+  return manifest.map((entry) => {
+    const sql = readFileSync(join(migrationsDir, entry.filename), 'utf-8');
+    return { ...entry, sql, checksum: computeChecksum(sql) };
+  });
+}
+
+export function loadMigrationManifest(migrationsDir: string): readonly MigrationManifestEntry[] {
   const entries = readdirSync(migrationsDir, { withFileTypes: true });
   const files: MigrationFile[] = [];
   const seenVersions = new Set<number>();
@@ -40,12 +54,10 @@ export function loadMigrationFiles(migrationsDir: string): readonly MigrationFil
     }
     seenVersions.add(version);
 
-    const fullPath = join(migrationsDir, entry.name);
-    const sql = readFileSync(fullPath, 'utf-8');
-    const checksum = computeChecksum(sql);
-
-    files.push({ version, name, filename: entry.name, sql, checksum });
+    files.push({ version, name, filename: entry.name, sql: '', checksum: '' });
   }
 
-  return files.sort((a, b) => a.version - b.version);
+  return files
+    .sort((a, b) => a.version - b.version)
+    .map(({ version, name, filename }) => ({ version, name, filename }));
 }