claude-nomad 0.26.2 → 0.28.0

package/src/push-leak-verdict.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared leak-scan verdict vocabulary for `cmdPush`. Both the dry-run preview
+ * (`previewPushLeaks` in `./push-preview.ts`) and the real-push scan
+ * (`scanPushVerdict` here) produce the same structured `LeakVerdict` so the
+ * one-line Leak scan row rendered inside the grouped tree cannot drift between
+ * the two paths. The multi-line `recovery` block (the `buildSessionAwareFatal`
+ * body) is printed by `cmdPush` BELOW the rendered tree on a leak.
+ *
+ * On a real push the scan still aborts the run: `cmdPush` renders the tree with
+ * the ✗ verdict row, then throws a `NomadFatal` carrying `recovery` so the
+ * existing catch prints the recovery block and sets a non-zero exit. The
+ * dry-run path never throws; it only sets `process.exitCode = 1`.
+ */
+
+import { failGlyph, green, okGlyph, red } from './color.ts';
+import { REPO_HOME } from './config.ts';
+import { gitleaksInstallHint } from './push-checks.ts';
+import {
+  type Finding,
+  buildSessionAwareFatal,
+  partitionFindings,
+  scanStagedTree,
+} from './push-gitleaks.ts';
+
+/**
+ * Structured leak-scan verdict.
+ *
+ * - `leak`: `true` only when findings were present (a scan crash is surfaced
+ *   via a ✗ `verdictRow` but is NOT a leak, so the dry-run path does not throw).
+ * - `verdictRow`: the rendered one-line Leak scan row (glyph embedded).
+ * - `recovery`: the `buildSessionAwareFatal` body on a leak, else `null`.
+ */
+export type LeakVerdict = {
+  leak: boolean;
+  verdictRow: string;
+  recovery: string | null;
+};
+
+/** Rendered clean Leak scan row (no findings). */
+export const noLeaksRow = (): string => `${green(okGlyph)} no leaks`;
+
+/** Rendered ✗ Leak scan row (caller supplies the message text). */
+export const failRow = (text: string): string => `${red(failGlyph)} ${text}`;
+
+/**
+ * Build the one-line ✗ Leak scan verdict row for a non-empty findings set,
+ * naming the affected session count. Falls back to the raw finding count when
+ * no finding matches the session-path pattern. Pure.
+ *
+ * @param findings - The non-empty findings array.
+ * @returns The rendered ✗ verdict row.
+ */
+export function leakVerdictRow(findings: Finding[]): string {
+  const { bySession } = partitionFindings(findings);
+  const n = bySession.size > 0 ? bySession.size : findings.length;
+  return failRow(`gitleaks detected secrets in ${n} session transcript(s)`);
+}
+
+/**
+ * Build the leak verdict for a non-empty findings set: the ✗ verdict row plus
+ * the `buildSessionAwareFatal` recovery body. Pure (no `process.exitCode`
+ * side effect; callers own that). Shared by the dry-run and real-push paths so
+ * the verdict row and recovery body cannot diverge.
+ *
+ * @param findings - The non-empty findings array.
+ * @returns A `leak=true` verdict carrying the ✗ row and recovery body.
+ */
+function leakFound(findings: Finding[]): LeakVerdict {
+  const { bySession, other } = partitionFindings(findings);
+  return {
+    leak: true,
+    verdictRow: leakVerdictRow(findings),
+    recovery: buildSessionAwareFatal(bySession, other),
+  };
+}
+
+/**
+ * Map a `scanStagedTree` result to a structured `LeakVerdict`, applying the
+ * shared side effect (`process.exitCode = 1` on findings or a scan crash). A
+ * `null` report (scan crash) yields a ✗ scan-failed row with `recovery=null`
+ * and is NOT classified as a `leak` (so the dry-run path neither throws nor
+ * offers a phantom drop-session hint). An empty array yields the clean
+ * `✓ no leaks` row. Non-empty findings yield the ✗ verdict row plus the
+ * `buildSessionAwareFatal` recovery body.
+ *
+ * @param findings - Output of `scanStagedTree`, or `null` on scan crash.
+ * @returns The structured verdict for the Leak scan section.
+ */
+export function verdictFromFindings(findings: Finding[] | null): LeakVerdict {
+  if (findings === null) {
+    process.exitCode = 1;
+    return {
+      leak: false,
+      verdictRow: failRow('scan failed, no parseable report'),
+      recovery: null,
+    };
+  }
+  if (findings.length === 0) return { leak: false, verdictRow: noLeaksRow(), recovery: null };
+  process.exitCode = 1;
+  return leakFound(findings);
+}
+
+/**
+ * Verdict for a scan that threw before producing a report (e.g. gitleaks/git
+ * absent on the dry-run path). Sets `process.exitCode = 1` and yields a ✗ row
+ * with `recovery=null`. Does not mark `leak` so the caller never throws.
+ *
+ * @param text - The ✗ row message text.
+ * @returns The structured scan-error verdict.
+ */
+export function verdictScanError(text: string): LeakVerdict {
+  process.exitCode = 1;
+  return { leak: false, verdictRow: failRow(text), recovery: null };
+}
+
+/**
+ * Run the real-push staged gitleaks scan (the same `scanStagedTree(REPO_HOME,
+ * true)` the push gate uses) and RETURN a structured `LeakVerdict` instead of
+ * throwing. This lets `cmdPush` render the grouped tree with the ✗ Leak scan
+ * row BEFORE re-raising the FATAL so the recovery block prints below the tree.
+ *
+ * On findings: `leak=true`, `verdictRow` is the ✗ row, `recovery` is the
+ * `buildSessionAwareFatal` body. On a clean scan: `✓ no leaks`. On a null
+ * report (scanner crash, malformed JSON): a ✗ scan-failed verdict with
+ * `recovery` set to the same scan-failed FATAL string `runGitleaksScan` would
+ * have thrown, so `cmdPush` still aborts. ENOENT (gitleaks/git absent) maps to
+ * the platform-aware install-hint FATAL as `recovery` with a ✗ row.
+ *
+ * @returns The structured verdict for the real-push Leak scan section.
+ */
+export function scanPushVerdict(): LeakVerdict {
+  let findings: Finding[] | null;
+  try {
+    findings = scanStagedTree(REPO_HOME, true);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return {
+        leak: true,
+        verdictRow: failRow('gitleaks not found'),
+        recovery: gitleaksInstallHint(),
+      };
+    }
+    throw err;
+  }
+  if (findings === null) {
+    return {
+      leak: true,
+      verdictRow: failRow('scan failed, no parseable report'),
+      recovery: 'gitleaks scan failed: no parseable JSON report. Review the gitleaks output above.',
+    };
+  }
+  if (findings.length === 0) return { leak: false, verdictRow: noLeaksRow(), recovery: null };
+  return leakFound(findings);
+}

package/src/push-preview.ts

@@ -0,0 +1,160 @@
+/**
+ * Push dry-run gitleaks leak preview.
+ *
+ * Stages a read-only copy of the session transcripts and extras that a real
+ * `nomad push` would send for this host, then runs `scanStagedTree` against
+ * that temp tree. The verdict is RETURNED as a structured
+ * `{ leak, verdictRow, recovery }` (rather than logged) so `cmdPush` can place
+ * `verdictRow` in the grouped tree's Leak scan section and print `recovery`
+ * (the `buildSessionAwareFatal` body) below the tree. On findings it still sets
+ * `process.exitCode = 1`.
+ *
+ * This module is the push-dry-run-only path. The `nomad doctor --check-shared`
+ * preflight (session-only scan, no extras) is unchanged and lives in
+ * `./commands.doctor.check-shared.ts`. Extras-in-doctor is a deferred
+ * follow-up (out of scope here).
+ */
+
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { dim, infoGlyph } from './color.ts';
+import { CLAUDE_HOME, HOST, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
+import { assertSafeLogical } from './extras-sync.guards.ts';
+import { copyExtras } from './extras-sync.ts';
+import { copyDirJsonlOnly } from './remap.ts';
+import { type LeakVerdict, verdictFromFindings, verdictScanError } from './push-leak-verdict.ts';
+import { scanStagedTree } from './push-gitleaks.ts';
+import { nowTimestamp } from './utils.fs.ts';
+import { encodePath } from './utils.json.ts';
+
+/** Rendered neutral Leak scan row when there was nothing to scan. */
+const NOTHING_TO_SCAN_ROW = `${dim(infoGlyph)} nothing to scan, no leaks`;
+
+/**
+ * Stage local session transcripts for HOST into `<tmpRoot>/shared/projects/<logical>/`
+ * using the same depth-0 `*.jsonl` filter as a real push. Builds the
+ * encoded-dir-to-logical reverse map from `map.projects` (skipping TBD or
+ * missing entries), then copies each matching `~/.claude/projects/<dir>/`.
+ *
+ * @param tmpRoot - Root of the throwaway staging tree.
+ * @param map - Parsed `path-map.json`.
+ * @returns Number of session directories staged.
+ */
+function stageSessions(tmpRoot: string, map: PathMap): number {
+  if (typeof map.projects !== 'object' || map.projects === null) return 0;
+
+  const reverse = new Map<string, string>();
+  for (const [logical, hosts] of Object.entries(map.projects)) {
+    assertSafeLogical(logical);
+    const p = hosts[HOST];
+    if (!p || p === 'TBD') continue;
+    reverse.set(encodePath(p), logical);
+  }
+
+  const localProjects = join(CLAUDE_HOME, 'projects');
+  if (!existsSync(localProjects)) return 0;
+
+  let staged = 0;
+  for (const dir of readdirSync(localProjects)) {
+    const logical = reverse.get(dir);
+    if (!logical) continue;
+    copyDirJsonlOnly(join(localProjects, dir), join(tmpRoot, 'shared', 'projects', logical));
+    staged++;
+  }
+  return staged;
+}
+
+/**
+ * Stage whitelisted extras for HOST into
+ * `<tmpRoot>/shared/extras/<logical>/<dirname>/`. Mirrors the skip semantics of
+ * `remapExtrasPush`: skips logicals with no host path or `'TBD'`, skips
+ * dirnames not in `SUPPORTED_EXTRAS`, and skips when the source path does not
+ * exist locally.
+ *
+ * Guards a non-object or missing `map.projects` defensively (mirroring
+ * `stageSessions`): a malformed map with an `extras` block but no usable
+ * `projects` stages nothing rather than throwing on the `map.projects[logical]`
+ * read.
+ *
+ * @param tmpRoot - Root of the throwaway staging tree.
+ * @param map - Parsed `path-map.json`.
+ * @returns Number of extras entries staged.
+ */
+function stageExtras(tmpRoot: string, map: PathMap): number {
+  if (typeof map.projects !== 'object' || map.projects === null) return 0;
+  const extrasMap = map.extras ?? {};
+  const whitelist: readonly string[] = SUPPORTED_EXTRAS;
+  let staged = 0;
+  for (const [logical, dirnames] of Object.entries(extrasMap)) {
+    assertSafeLogical(logical);
+    const localRoot = map.projects[logical]?.[HOST];
+    if (!localRoot || localRoot === 'TBD') continue;
+    for (const dirname of dirnames) {
+      if (!whitelist.includes(dirname)) continue;
+      const src = join(localRoot, dirname);
+      if (!existsSync(src)) continue;
+      const dst = join(tmpRoot, 'shared', 'extras', logical, dirname);
+      copyExtras(src, dst);
+      staged++;
+    }
+  }
+  return staged;
+}
+
+/**
+ * Run a read-only gitleaks leak preview of what `nomad push` would stage for
+ * this host: both mapped session transcripts
+ * (`shared/projects/<logical>/*.jsonl`) and opted-in extras
+ * (`shared/extras/<logical>/<dirname>`).
+ *
+ * Stages the content into a throwaway tree under
+ * `~/.cache/claude-nomad/push-preview-tree-<stamp>` and runs `scanStagedTree`
+ * with `forwardStreams=false` (read-only: no gitleaks stderr/stdout leak to the
+ * terminal). The temp tree is always removed in a `finally`, regardless of
+ * whether the scan found leaks, crashed, or returned clean. `REPO_HOME/shared`
+ * is never written.
+ *
+ * Returns a structured `LeakVerdict` rather than logging the verdict line so
+ * `cmdPush` can render `verdictRow` in the Leak scan section and print
+ * `recovery` below the tree. Side effects preserved: `process.exitCode = 1` on
+ * findings AND on a scan crash. A scan that throws maps to a ✗ scan-error row
+ * with `exitCode = 1`: ENOENT (gitleaks/git absent) keeps the "not on PATH"
+ * wording, any other error (e.g. EACCES) surfaces its real message so the
+ * cause is not mislabeled. Nothing-to-scan maps to a neutral ℹ︎ row.
+ *
+ * Fails closed before any copy: an unsafe `logical` key (path separator or
+ * `..`) raised by `assertSafeLogical` in the staging step propagates out as a
+ * `NomadFatal` to `cmdPush`, and the `finally` still removes the temp tree.
+ *
+ * @param map - Parsed `path-map.json` (already in scope from `cmdPush`).
+ * @returns The structured verdict for the Leak scan section.
+ */
+export function previewPushLeaks(map: PathMap): LeakVerdict {
+  const cacheDir = join(homedir(), '.cache', 'claude-nomad');
+  mkdirSync(cacheDir, { recursive: true });
+  const stamp = `${nowTimestamp()}-${process.pid}-${randomBytes(4).toString('hex')}`;
+  const tmpRoot = join(cacheDir, `push-preview-tree-${stamp}`);
+
+  try {
+    const sessionCount = stageSessions(tmpRoot, map);
+    const extrasCount = stageExtras(tmpRoot, map);
+    if (sessionCount + extrasCount === 0) {
+      return { leak: false, verdictRow: NOTHING_TO_SCAN_ROW, recovery: null };
+    }
+    let findings: ReturnType<typeof scanStagedTree>;
+    try {
+      findings = scanStagedTree(tmpRoot);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        return verdictScanError('scan error (git or gitleaks not on PATH)');
+      }
+      return verdictScanError(`scan error: ${(err as Error).message}`);
+    }
+    return verdictFromFindings(findings);
+  } finally {
+    rmSync(tmpRoot, { recursive: true, force: true });
+  }
+}

package/src/remap.ts

@@ -49,22 +49,31 @@ export function copyDirJsonlOnly(src: string, dst: string): void {
 /**
  * Pull: copy from repo's logical project names into local path-encoded dirs.
  *
- * Returns `{ unmapped: N }` where `N` counts path-map entries skipped for
- * this host (either `'TBD'` placeholder or no entry for `HOST`). The count
- * is consumed by `computePreview` and the future summary line.
+ * Returns `{ unmapped, pulled, wouldPull }`. `unmapped` counts path-map entries
+ * skipped for this host (`'TBD'` placeholder or no entry for `HOST`); `pulled`
+ * holds logical names copied (wet), `wouldPull` those that would copy under
+ * `dryRun`. The arrays let cmdPull render a grouped tree; the wet path no longer
+ * logs per-project `pulled X -> Y` / `skip ...` inline. The dry-run path KEEPS
+ * its `would overwrite:` line because `computePreview` renders those as the
+ * Projects section of `nomad diff` and the dry-run pull preview. The degenerate
+ * early-return `log(...)` (not a per-project skip) is preserved.
  *
- * `opts.dryRun` (default `false`): when `true`, log `would overwrite:` lines
- * instead of calling `backupBeforeWrite` + `copyDir`. The unmapped count is
- * computed identically in both modes.
+ * @param ts - backup timestamp namespace.
+ * @param opts.dryRun - when `true`, collect `wouldPull` and log would-overwrite.
  */
-export function remapPull(ts: string, opts: { dryRun?: boolean } = {}): { unmapped: number } {
+export function remapPull(
+  ts: string,
+  opts: { dryRun?: boolean } = {},
+): { unmapped: number; pulled: string[]; wouldPull: string[] } {
   const dryRun = opts.dryRun === true;
   let unmapped = 0;
+  const pulled: string[] = [];
+  const wouldPull: string[] = [];
   const mapPath = join(REPO_HOME, 'path-map.json');
   const repoProjects = join(REPO_HOME, 'shared', 'projects');
   if (!existsSync(mapPath) || !existsSync(repoProjects)) {
     log('no path-map or repo projects dir; skipping session remap');
-    return { unmapped: 0 };
+    return { unmapped: 0, pulled, wouldPull };
   }
 
   const map = readJson<PathMap>(mapPath);
@@ -73,29 +82,28 @@ export function remapPull(ts: string, opts: { dryRun?: boolean } = {}): { unmapp
 
   for (const [logical, hosts] of Object.entries(map.projects)) {
     const localPath = hosts[HOST];
-    if (localPath === 'TBD') {
+    if (!localPath || localPath === 'TBD') {
       unmapped++;
-      log(`skip ${logical}: placeholder path for ${HOST}`);
-      continue;
-    }
-    if (!localPath) {
-      unmapped++;
-      log(`skip ${logical}: no path for ${HOST}`);
       continue;
     }
     const src = join(repoProjects, logical);
     if (!existsSync(src)) continue;
     const dst = join(localProjects, encodePath(localPath));
     if (dryRun) {
+      // KEEP this would-overwrite log: computePreview (backing both `nomad
+      // diff` and the dry-run pull preview) renders these lines as its
+      // Projects section, so removing them regresses that output. The grouped
+      // tree is built only on the WET path, which consumes `pulled` instead.
+      wouldPull.push(logical);
       log(`would overwrite: ${dst} (from ${src})`);
       continue;
     }
     // Snapshot prior encoded-path-dir state BEFORE copyDir overwrites it.
     backupBeforeWrite(dst, ts);
     copyDir(src, dst);
-    log(`pulled ${logical} -> ${encodePath(localPath)}`);
+    pulled.push(logical);
   }
-  return { unmapped };
+  return { unmapped, pulled, wouldPull };
 }
 
 /**
@@ -156,20 +164,32 @@ function buildReverseMap(map: PathMap): Map<string, string> {
  * refuse the push before any `shared/projects/` content is written. Detection
  * runs during the reverse-map build, so it fires under `dryRun` too.
  *
- * `opts.dryRun` (default `false`): when `true`, log `would push:` lines
- * instead of calling `backupRepoWrite` + `copyDir`. Collision detection
- * runs identically in both modes.
+ * `opts.dryRun` (default `false`): when `true`, collect `wouldPush` without
+ * calling `backupRepoWrite` + `copyDir`. Collision detection runs identically
+ * in both modes.
+ *
+ * Returns `pushed` (logical names actually copied, wet mode) and `wouldPush`
+ * (logical names under `dryRun`) alongside the counts so cmdPush can render a
+ * grouped tree. This function no longer logs per-project `pushed X -> Y` /
+ * `skip ... not in path-map` / `would push:` lines inline; the
+ * `copyDirJsonlOnly` extension-skip log is a separate file-filter concern and
+ * is preserved, as are the degenerate early-return `log(...)` lines.
+ *
+ * @param ts - backup timestamp namespace.
+ * @param opts.dryRun - when `true`, collect `wouldPush` without mutating.
  */
 export function remapPush(
   ts: string,
   opts: { dryRun?: boolean } = {},
-): { unmapped: number; collisions: number } {
+): { unmapped: number; collisions: number; pushed: string[]; wouldPush: string[] } {
   const dryRun = opts.dryRun === true;
   let unmapped = 0;
+  const pushed: string[] = [];
+  const wouldPush: string[] = [];
   const mapPath = join(REPO_HOME, 'path-map.json');
   if (!existsSync(mapPath)) {
     log('no path-map.json; skipping session export');
-    return { unmapped: 0, collisions: 0 };
+    return { unmapped: 0, collisions: 0, pushed, wouldPush };
   }
 
   const map = readJson<PathMap>(mapPath);
@@ -177,7 +197,7 @@ export function remapPush(
   const repoProjects = join(REPO_HOME, 'shared', 'projects');
 
   const reverse = buildReverseMap(map);
-  if (!existsSync(localProjects)) return { unmapped, collisions: 0 };
+  if (!existsSync(localProjects)) return { unmapped, collisions: 0, pushed, wouldPush };
   // Create the repo destination only after collision detection passes and we
   // know there is something to push, so a failing or no-op push is fully
   // side-effect-free (no empty shared/projects/ left behind).
@@ -187,12 +207,11 @@ export function remapPush(
     const logical = reverse.get(dir);
     if (!logical) {
       unmapped++;
-      log(`skip ${dir}: not in path-map for ${HOST}`);
       continue;
     }
     const repoDst = join(repoProjects, logical);
     if (dryRun) {
-      log(`would push: ${dir} -> ${logical}`);
+      wouldPush.push(logical);
       continue;
     }
     // Snapshot repo-side destination before copyDir clobbers it. Git
@@ -201,7 +220,7 @@ export function remapPush(
     // path. Symmetric with remapPull's backupBeforeWrite on the local dst.
     backupRepoWrite(repoDst, ts, REPO_HOME);
     copyDirJsonlOnly(join(localProjects, dir), repoDst);
-    log(`pushed ${dir} -> ${logical}`);
+    pushed.push(logical);
   }
-  return { unmapped, collisions: 0 };
+  return { unmapped, collisions: 0, pushed, wouldPush };
 }

package/src/settings-keys.ts

@@ -0,0 +1,124 @@
+/**
+ * Top-level keys recognized in `~/.claude/settings.json`, used by the
+ * `nomad doctor` schema-drift check. Split by provenance so the schema half
+ * can be re-synced mechanically.
+ *
+ * `SCHEMA_KEYS`: the documented properties from the official Claude Code
+ * settings JSON schema (https://json.schemastore.org/claude-code-settings.json).
+ * Regenerated by scripts/sync-settings-keys.mjs (run weekly by the
+ * settings-schema-drift workflow); do not hand-edit this array.
+ *
+ * `APP_ONLY_KEYS`: keys Claude Code writes to settings.json that the published
+ * schema has not caught up to yet (the running app runs ahead of the schema).
+ * These cannot be derived from the schema and are hand-maintained.
+ */
+export const SCHEMA_KEYS = [
+  '$schema',
+  'agent',
+  'allowedChannelPlugins',
+  'allowedHttpHookUrls',
+  'allowedMcpServers',
+  'allowManagedHooksOnly',
+  'allowManagedMcpServersOnly',
+  'allowManagedPermissionRulesOnly',
+  'alwaysThinkingEnabled',
+  'apiKeyHelper',
+  'attribution',
+  'autoMemoryDirectory',
+  'autoMemoryEnabled',
+  'autoMode',
+  'autoUpdatesChannel',
+  'availableModels',
+  'awsAuthRefresh',
+  'awsCredentialExport',
+  'blockedMarketplaces',
+  'channelsEnabled',
+  'claudeMdExcludes',
+  'cleanupPeriodDays',
+  'companyAnnouncements',
+  'defaultShell',
+  'deniedMcpServers',
+  'disableAllHooks',
+  'disableDeepLinkRegistration',
+  'disabledMcpjsonServers',
+  'disableSkillShellExecution',
+  'effortLevel',
+  'enableAllProjectMcpServers',
+  'enabledMcpjsonServers',
+  'enabledPlugins',
+  'env',
+  'extraKnownMarketplaces',
+  'fastMode',
+  'fastModePerSessionOptIn',
+  'feedbackSurveyRate',
+  'fileSuggestion',
+  'forceLoginMethod',
+  'forceLoginOrgUUID',
+  'forceRemoteSettingsRefresh',
+  'hooks',
+  'httpHookAllowedEnvVars',
+  'includeCoAuthoredBy',
+  'includeGitInstructions',
+  'language',
+  'minimumVersion',
+  'model',
+  'modelOverrides',
+  'otelHeadersHelper',
+  'outputStyle',
+  'parentSettingsBehavior',
+  'permissions',
+  'plansDirectory',
+  'pluginConfigs',
+  'pluginTrustMessage',
+  'prefersReducedMotion',
+  'prUrlTemplate',
+  'respectGitignore',
+  'sandbox',
+  'showClearContextOnPlanAccept',
+  'showThinkingSummaries',
+  'showTurnDuration',
+  'skillOverrides',
+  'skipDangerousModePermissionPrompt',
+  'skippedMarketplaces',
+  'skippedPlugins',
+  'skipWebFetchPreflight',
+  'spinnerTipsEnabled',
+  'spinnerTipsOverride',
+  'spinnerVerbs',
+  'statusLine',
+  'strictKnownMarketplaces',
+  'strictPluginOnlyCustomization',
+  'subagentStatusLine',
+  'teammateMode',
+  'terminalProgressBarEnabled',
+  'tui',
+  'useAutoModeDuringPlan',
+  'viewMode',
+  'voiceEnabled',
+  'worktree',
+  'wslInheritsWindowsSettings',
+];
+
+export const APP_ONLY_KEYS = [
+  'agentPushNotifEnabled',
+  'agents',
+  'apiKeyHelperTimeoutMs',
+  'awsLoginRefresh',
+  'awsRegion',
+  'awsRetryMode',
+  'disableNonEssentialModelCalls',
+  'enabledExperimentalFeatures',
+  'inputNeededNotifEnabled',
+  'installMethod',
+  'pluginGroups',
+  'pluginRepositoryEnabled',
+  'pluginsLocalConfig',
+  'proxy',
+  'skipAutoPermissionPrompt',
+  'statsig',
+  'subagents',
+  'theme',
+];
+
+/** Union of schema-documented and app-only settings keys; unknown top-level keys trigger a doctor WARN. */
+export const KNOWN_SETTINGS_KEYS = new Set<string>([...SCHEMA_KEYS, ...APP_ONLY_KEYS]);