@massu/core 1.7.0 → 1.9.0

package/src/commands/permissions.ts

@@ -0,0 +1,150 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * `massu permissions <subcommand>` — MCP permission lifecycle CLI.
+ *
+ * Subcommands (each is documented at https://massu.ai/docs/reference/cli-reference):
+ *   install      Seed `mcp__massu__*` into permissions.allow + propagate global
+ *                defaultMode (idempotent, kept-because-edited preservation).
+ *   verify       Read-only check; exit 0 if all canonical entries present, else 1.
+ *   check-drift  Extended diagnostic (4 drift kinds, severity-mapped exit codes).
+ *
+ * Exit code matrix for `check-drift` (highest severity wins when multiple kinds present):
+ *   0 = clean
+ *   1 = missing-allow
+ *   2 = invalid-default-mode
+ *   3 = unknown-key
+ *   4 = strips-global-defaultmode
+ *
+ * Mirrors the existing `handleConfigSubcommand` dispatch pattern at cli.ts.
+ */
+
+import { resolve } from 'path';
+import { getConfig } from '../config.ts';
+import {
+  installPermissions,
+  verifyPermissions,
+  checkPermissionsDrift,
+  type DriftKind,
+} from '../permissions.ts';
+import { runWithManifest } from './install-commands.ts';
+
+function resolveClaudeDir(): string {
+  let claudeDirName = '.claude';
+  try {
+    claudeDirName = getConfig().conventions?.claudeDirName ?? '.claude';
+  } catch {
+    claudeDirName = '.claude';
+  }
+  return resolve(process.cwd(), claudeDirName);
+}
+
+const DRIFT_KIND_EXIT_CODE: Record<DriftKind, number> = {
+  'missing-allow': 1,
+  'invalid-default-mode': 2,
+  'unknown-key': 3,
+  'strips-global-defaultmode': 4,
+};
+
+export async function handlePermissionsSubcommand(
+  args: string[],
+): Promise<{ exitCode: number }> {
+  const sub = args[0];
+
+  switch (sub) {
+    case 'install': {
+      const claudeDir = resolveClaudeDir();
+      const result = runWithManifest(claudeDir, (manifest) =>
+        installPermissions(claudeDir, manifest, { silent: false }),
+      );
+      // Final user-facing summary line on stdout
+      if (result.installed > 0) {
+        process.stdout.write(
+          'Wrote merged permissions block to .claude/settings.local.json.\n',
+        );
+      } else if (result.skipped > 0) {
+        process.stdout.write('Permissions already in sync — no changes.\n');
+      } else if (result.kept > 0) {
+        process.stdout.write(
+          'Operator-edited permissions block preserved. Run `npx massu permissions check-drift` to inspect.\n',
+        );
+      }
+      return { exitCode: 0 };
+    }
+
+    case 'verify': {
+      const claudeDir = resolveClaudeDir();
+      const { missing } = verifyPermissions(claudeDir);
+      if (missing.length === 0) {
+        process.stdout.write('All MCP allowlist entries present.\n');
+        return { exitCode: 0 };
+      }
+      for (const entry of missing) {
+        process.stderr.write(`missing: ${entry}\n`);
+      }
+      return { exitCode: 1 };
+    }
+
+    case 'check-drift': {
+      const claudeDir = resolveClaudeDir();
+      const { driftItems } = checkPermissionsDrift(claudeDir);
+      if (driftItems.length === 0) {
+        process.stdout.write('No permission drift detected.\n');
+        return { exitCode: 0 };
+      }
+      // Highest-severity kind wins for exit code
+      let highest = 0;
+      for (const item of driftItems) {
+        const code = DRIFT_KIND_EXIT_CODE[item.kind];
+        if (code > highest) highest = code;
+        process.stderr.write(
+          `drift[${item.kind}]: ${item.detail} — remediation: ${item.remediation}\n`,
+        );
+      }
+      return { exitCode: highest };
+    }
+
+    case '--help':
+    case '-h':
+    case undefined: {
+      printPermissionsHelp();
+      return { exitCode: 0 };
+    }
+
+    default: {
+      process.stderr.write(`massu: unknown permissions subcommand: ${sub}\n`);
+      printPermissionsHelp();
+      return { exitCode: 1 };
+    }
+  }
+}
+
+export function printPermissionsHelp(): void {
+  process.stdout.write(`
+massu permissions <subcommand>
+
+Subcommands:
+  install       Seed mcp__massu__* into .claude/settings.local.json's permissions.allow.
+                  Also propagates global defaultMode (from ~/.claude/settings.json) into
+                  the project-local file to prevent the merge-replacement trap (see
+                  https://massu.ai/docs/reference/cli-reference#permissions-trap).
+                  Idempotent. Preserves operator-edited values.
+
+  verify        Read-only check that all canonical MCP allowlist entries are present.
+                  Exit 0 if clean, exit 1 with one diagnostic line per missing entry.
+
+  check-drift   Extended diagnostic surfacing 4 drift kinds:
+                  - missing-allow             (exit 1) — canonical entries missing
+                  - invalid-default-mode      (exit 2) — defaultMode requires launch flag
+                  - unknown-key               (exit 3) — undocumented top-level setting
+                  - strips-global-defaultmode (exit 4) — project-local would strip global value
+
+Examples:
+  npx massu permissions install
+  npx massu permissions verify
+  npx massu permissions check-drift
+
+Documentation: https://massu.ai/docs/reference/cli-reference#massu-permissions
+`);
+}

package/src/lib/settings-local.ts

@@ -0,0 +1,110 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Shared IO helper for `.claude/settings.local.json` and the user-global
+ * `~/.claude/settings.json`. SSOT for read+atomic-write semantics; closes
+ * the pre-existing non-atomic-write bug at init.ts installHooks (previously
+ * used writeFileSync which was vulnerable to SIGINT-between-truncate-and-write).
+ *
+ * Three exports:
+ *   - readSettingsLocal(claudeDir): safe-parse of <claudeDir>/settings.local.json
+ *   - writeSettingsLocalAtomic(claudeDir, settings): atomic write of same
+ *   - readSettingsAtPath(absolutePath): generic safe-parse used by readSettingsLocal
+ *     AND by permissions.ts:readGlobalSettings() reading ~/.claude/settings.json
+ *
+ * Plus the atomicWriteFile primitive (moved here from install-commands.ts to
+ * centralize). All consumers — install-commands manifest save, install-commands
+ * per-file syncs, init.ts installHooks, doctor.ts hooks-config check — share
+ * this single source of truth for filesystem IO.
+ */
+
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeSync,
+} from 'fs';
+import { dirname, resolve } from 'path';
+
+/**
+ * Atomic file write — tmp + fsync + rename. Moved from install-commands.ts so
+ * it can be reused by settings-local IO without circular import.
+ *
+ * Writes via openSync + writeSync + fsyncSync + closeSync + renameSync so the
+ * data hits the platter before the rename. On any error, removes the tmp file.
+ * Tmp filename includes process.pid to avoid clashes with concurrent installs.
+ */
+export function atomicWriteFile(targetPath: string, content: string, mode = 0o644): void {
+  const tmpPath = `${targetPath}.${process.pid}.tmp`;
+  try {
+    const fd = openSync(tmpPath, 'w', mode);
+    try {
+      const buf = Buffer.from(content, 'utf-8');
+      writeSync(fd, buf, 0, buf.length, 0);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(tmpPath, targetPath);
+  } catch (err) {
+    if (existsSync(tmpPath)) {
+      try { rmSync(tmpPath, { force: true }); } catch { /* ignore */ }
+    }
+    throw err;
+  }
+}
+
+/**
+ * Generic safe-parse of a JSON settings file. Used by readSettingsLocal
+ * (project-local) AND permissions.ts:readGlobalSettings (user-global).
+ *
+ * Returns `{}` on any failure path: missing file, unreadable, malformed JSON,
+ * non-object root. This contract lets callers do `(settings.permissions as any)`
+ * shape-checks defensively without a separate "does the file exist" pre-check.
+ */
+export function readSettingsAtPath(absolutePath: string): Record<string, unknown> {
+  if (!existsSync(absolutePath)) {
+    return {};
+  }
+  try {
+    const raw = readFileSync(absolutePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Read `<claudeDir>/settings.local.json`. Returns `{}` on missing/corrupt.
+ */
+export function readSettingsLocal(claudeDir: string): Record<string, unknown> {
+  return readSettingsAtPath(resolve(claudeDir, 'settings.local.json'));
+}
+
+/**
+ * Atomically write `<claudeDir>/settings.local.json`. Creates the parent
+ * directory if missing. JSON.stringify with 2-space indent + trailing newline
+ * (matches the existing convention in init.ts installHooks).
+ */
+export function writeSettingsLocalAtomic(
+  claudeDir: string,
+  settings: Record<string, unknown>,
+): void {
+  const targetPath = resolve(claudeDir, 'settings.local.json');
+  const dir = dirname(targetPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const content = JSON.stringify(settings, null, 2) + '\n';
+  atomicWriteFile(targetPath, content);
+}

package/src/permissions.ts

@@ -0,0 +1,422 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * SSOT for MCP permission seeding, verification, and drift detection.
+ *
+ * Public surface:
+ *   MASSU_PERMISSION_ENTRIES     — canonical glob entries (currently ['mcp__massu__*'])
+ *   LAUNCH_FLAG_REQUIRED_MODES   — defaultMode values that require launch flag
+ *                                   per https://code.claude.com/docs/en/permission-modes
+ *                                   (cannot be activated from settings file alone)
+ *   findMissingEntries           — pure SSOT helper used by writer + verifier
+ *   detectInvalidDefaultMode     — checks settings.permissions.defaultMode against
+ *                                   LAUNCH_FLAG_REQUIRED_MODES
+ *   readGlobalSettings           — reads ~/.claude/settings.json safely
+ *   mergedPermissionState        — pure merge function: allow ∪ canonical;
+ *                                   defaultMode = local override OR global OR omit;
+ *                                   deny/ask preserved from local
+ *   installPermissions           — read-merge-atomic-write-assert pipeline
+ *   verifyPermissions            — read-only canonical-entry check
+ *   checkPermissionsDrift        — extended diagnostic (4 drift kinds)
+ *   InstallPermissionsAssertionError — fail-loud post-write assertion type
+ *
+ * v3 fix: writes the FULL merged permissions block (not just .allow), eliminating
+ * the merge-replacement trap empirically observed 2026-05-14 where a project-local
+ * `permissions` object that omits defaultMode silently strips the global value.
+ * See docs/plans/2026-05-14-1.8.0-mcp-permission-seeding.md §0.5 for evidence
+ * (F15+F16+F17) and the docs gap at code.claude.com/docs/en/permissions.
+ *
+ * Manifest convention: synthetic non-file entries use prefix `__settings__/`.
+ * This module uses `__settings__/permissions` as the manifest key for the
+ * full merged permissions block hash (3-hash kept-because-edited pattern).
+ */
+
+import { createHash } from 'crypto';
+import { homedir } from 'os';
+import { join } from 'path';
+import { getConfig } from './config.ts';
+import type { Manifest } from './commands/install-commands.ts';
+import {
+  readSettingsAtPath,
+  readSettingsLocal,
+  writeSettingsLocalAtomic,
+} from './lib/settings-local.ts';
+
+// ============================================================
+// SSOT constants
+// ============================================================
+
+/**
+ * Canonical MCP allowlist entries seeded by massu into project-local
+ * `.claude/settings.local.json`. Currently a single glob covering all
+ * `mcp__massu__<tool>` invocations (73+ tools as of 1.7.0). Future
+ * additions require an ADR + explicit operator approval per CLAUDE.md
+ * `### Default Permissions` policy.
+ *
+ * Format validated against https://code.claude.com/docs/en/permissions § MCP:
+ * "`mcp__puppeteer__*` wildcard syntax that also matches all tools from the
+ * `puppeteer` server".
+ */
+export const MASSU_PERMISSION_ENTRIES = ['mcp__massu__*'] as const;
+
+/**
+ * `defaultMode` values that CANNOT be activated from a settings file alone;
+ * each requires a corresponding `--permission-mode <mode>` (or equivalent)
+ * launch flag per https://code.claude.com/docs/en/permission-modes.
+ *
+ * Values OK from settings: `default`, `acceptEdits`, `plan`.
+ * Values requiring launch flag: included in this constant.
+ *
+ * Used by detectInvalidDefaultMode + checkPermissionsDrift.
+ */
+export const LAUNCH_FLAG_REQUIRED_MODES = ['bypassPermissions', 'auto', 'dontAsk'] as const;
+
+// ============================================================
+// Type surface
+// ============================================================
+
+export type DriftKind =
+  | 'missing-allow'
+  | 'invalid-default-mode'
+  | 'unknown-key'
+  | 'strips-global-defaultmode';
+
+export interface DriftItem {
+  kind: DriftKind;
+  detail: string;
+  remediation: string;
+}
+
+export interface MergedPermissions {
+  allow: string[];
+  defaultMode?: string;
+  deny?: string[];
+  ask?: string[];
+}
+
+export class InstallPermissionsAssertionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InstallPermissionsAssertionError';
+  }
+}
+
+// ============================================================
+// Pure helpers
+// ============================================================
+
+/** Deterministic JSON serialization with sorted keys. */
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalJson).join(',') + ']';
+  }
+  const keys = Object.keys(value as Record<string, unknown>).sort();
+  const parts = keys.map((k) => {
+    const v = (value as Record<string, unknown>)[k];
+    if (v === undefined) return '';
+    return JSON.stringify(k) + ':' + canonicalJson(v);
+  }).filter((s) => s !== '');
+  return '{' + parts.join(',') + '}';
+}
+
+function sha256Hex(input: string): string {
+  return createHash('sha256').update(input, 'utf-8').digest('hex');
+}
+
+export function findMissingEntries(allow: readonly string[]): string[] {
+  const allowSet = new Set(allow);
+  return MASSU_PERMISSION_ENTRIES.filter((entry) => !allowSet.has(entry));
+}
+
+export function detectInvalidDefaultMode(
+  settings: Record<string, unknown>,
+): { invalid: boolean; mode?: string; reason?: string } {
+  const permissions = settings.permissions as { defaultMode?: unknown } | undefined;
+  const mode = permissions?.defaultMode;
+  if (typeof mode !== 'string') {
+    return { invalid: false };
+  }
+  if ((LAUNCH_FLAG_REQUIRED_MODES as readonly string[]).includes(mode)) {
+    return {
+      invalid: true,
+      mode,
+      reason:
+        `defaultMode "${mode}" requires --permission-mode launch flag per ` +
+        `https://code.claude.com/docs/en/permission-modes — settings-file value alone is inert. ` +
+        `Remediation: launch with --permission-mode ${mode} OR change defaultMode to one of {default, acceptEdits, plan}.`,
+    };
+  }
+  return { invalid: false };
+}
+
+/**
+ * Read user-global ~/.claude/settings.json safely. Returns {} on any failure
+ * (missing, corrupt, permission denied). Honors $HOME via os.homedir().
+ */
+export function readGlobalSettings(): Record<string, unknown> {
+  return readSettingsAtPath(join(homedir(), '.claude', 'settings.json'));
+}
+
+/**
+ * Pure merge function. Computes the target `permissions` block for the
+ * project-local settings.local.json.
+ *
+ * Rules:
+ *   - allow: dedupe(local.allow ∪ canonical), preserving local order; canonical
+ *     entries that are not already present are appended at the end
+ *   - defaultMode: local override wins (user choice respected); else global
+ *     value is propagated; else key is OMITTED entirely (no key in output object,
+ *     not `undefined` — verified by PERM-DRIFT-15)
+ *   - deny: preserved from local verbatim (or omitted if local has none)
+ *   - ask: preserved from local verbatim (or omitted if local has none)
+ */
+export function mergedPermissionState(
+  global: Record<string, unknown>,
+  local: Record<string, unknown>,
+  canonical: readonly string[],
+): MergedPermissions {
+  const globalPerm = (global.permissions as Record<string, unknown> | undefined) ?? {};
+  const localPerm = (local.permissions as Record<string, unknown> | undefined) ?? {};
+
+  const localAllow = Array.isArray(localPerm.allow)
+    ? (localPerm.allow as unknown[]).filter((e): e is string => typeof e === 'string')
+    : [];
+  const allowSet = new Set(localAllow);
+  const allow = [...localAllow];
+  for (const entry of canonical) {
+    if (!allowSet.has(entry)) {
+      allow.push(entry);
+      allowSet.add(entry);
+    }
+  }
+
+  const result: MergedPermissions = { allow };
+
+  // defaultMode resolution
+  if (typeof localPerm.defaultMode === 'string') {
+    result.defaultMode = localPerm.defaultMode;
+  } else if (typeof globalPerm.defaultMode === 'string') {
+    result.defaultMode = globalPerm.defaultMode;
+  }
+  // Else: key OMITTED (not undefined, not present at all)
+
+  if (Array.isArray(localPerm.deny)) {
+    result.deny = (localPerm.deny as unknown[]).filter((e): e is string => typeof e === 'string');
+  }
+  if (Array.isArray(localPerm.ask)) {
+    result.ask = (localPerm.ask as unknown[]).filter((e): e is string => typeof e === 'string');
+  }
+
+  return result;
+}
+
+// ============================================================
+// installPermissions (read-merge-atomic-write-assert pipeline)
+// ============================================================
+
+const MANIFEST_KEY_PERMISSIONS = '__settings__/permissions';
+
+function resolveClaudeDir(claudeDir: string): string {
+  return claudeDir;
+}
+
+function hashOfPermissions(perm: Record<string, unknown> | MergedPermissions): string {
+  return sha256Hex(canonicalJson(perm));
+}
+
+/**
+ * Install the canonical massu permission entries plus any propagated
+ * defaultMode from global settings. Mirrors the install-commands.ts 3-hash
+ * kept-because-edited pattern for operator-edit preservation.
+ *
+ * Cases (mirrors install-commands.ts:syncDirectory file-write logic):
+ *   1. existing == expected           → skipped:1 (idempotent)
+ *   2. no last-installed hash         → first install, write merged → installed:1
+ *   3. existing == last-installed     → operator did not edit; reapply merge → installed:1
+ *   4. existing != last-installed     → operator edited after last install → kept:1 (preserve)
+ *
+ * Post-write: re-reads disk and asserts the merged state survived. If a
+ * defaultMode was decided (from local or global) but is absent on disk,
+ * throws `InstallPermissionsAssertionError`.
+ */
+export function installPermissions(
+  claudeDir: string,
+  manifest: Manifest,
+  opts: { silent?: boolean; global?: Record<string, unknown> } = {},
+): { installed: number; kept: number; skipped: number } {
+  const resolvedDir = resolveClaudeDir(claudeDir);
+  const global = opts.global ?? readGlobalSettings();
+  const local = readSettingsLocal(resolvedDir);
+
+  const merged = mergedPermissionState(global, local, MASSU_PERMISSION_ENTRIES);
+  const expectedHash = hashOfPermissions(merged);
+
+  const existingPerm = (local.permissions as Record<string, unknown> | undefined) ?? undefined;
+  const existingHash = existingPerm ? hashOfPermissions(existingPerm) : undefined;
+  const lastInstalledHash = manifest.entries[MANIFEST_KEY_PERMISSIONS];
+
+  // Case 1: already in sync
+  if (existingHash === expectedHash) {
+    manifest.entries[MANIFEST_KEY_PERMISSIONS] = expectedHash;
+    if (!opts.silent) {
+      process.stderr.write(
+        `  Permissions: already in sync (allow: ${merged.allow.length} entries; defaultMode: ${merged.defaultMode ?? 'omitted'}).\n`,
+      );
+    }
+    return { installed: 0, kept: 0, skipped: 1 };
+  }
+
+  // Case 4: operator edited after last install — preserve
+  if (lastInstalledHash !== undefined && existingHash !== lastInstalledHash) {
+    if (!opts.silent) {
+      process.stderr.write(
+        `  Permissions: operator-edited since last install — preserving. ` +
+          `Use \`npx massu permissions check-drift\` to inspect.\n`,
+      );
+    }
+    return { installed: 0, kept: 1, skipped: 0 };
+  }
+
+  // Case 2/3: write merged
+  const nextSettings: Record<string, unknown> = { ...local, permissions: merged };
+  writeSettingsLocalAtomic(resolvedDir, nextSettings);
+  manifest.entries[MANIFEST_KEY_PERMISSIONS] = expectedHash;
+
+  // Post-write fail-loud assertion: re-read, confirm defaultMode propagation
+  const onDisk = readSettingsLocal(resolvedDir);
+  const onDiskPerm = (onDisk.permissions as Record<string, unknown> | undefined) ?? {};
+  if (merged.defaultMode !== undefined) {
+    const diskDefaultMode = onDiskPerm.defaultMode;
+    if (diskDefaultMode !== merged.defaultMode) {
+      throw new InstallPermissionsAssertionError(
+        `Post-write assertion failed: expected permissions.defaultMode="${merged.defaultMode}" on disk, ` +
+          `got ${JSON.stringify(diskDefaultMode)}. This indicates a filesystem race or write failure.`,
+      );
+    }
+  }
+  const diskAllow = Array.isArray(onDiskPerm.allow) ? (onDiskPerm.allow as unknown[]) : [];
+  for (const entry of MASSU_PERMISSION_ENTRIES) {
+    if (!diskAllow.includes(entry)) {
+      throw new InstallPermissionsAssertionError(
+        `Post-write assertion failed: canonical entry "${entry}" missing from permissions.allow on disk.`,
+      );
+    }
+  }
+
+  if (!opts.silent) {
+    process.stderr.write(
+      `  Wrote merged permissions block to .claude/settings.local.json ` +
+        `(allow: ${merged.allow.length} entries; defaultMode: ${merged.defaultMode ?? 'omitted'}).\n`,
+    );
+  }
+  return { installed: 1, kept: 0, skipped: 0 };
+}
+
+// ============================================================
+// verifyPermissions (read-only)
+// ============================================================
+
+export function verifyPermissions(claudeDir: string): {
+  missing: string[];
+  allowList: readonly string[];
+} {
+  const local = readSettingsLocal(claudeDir);
+  const permissions = (local.permissions as { allow?: unknown[] } | undefined) ?? {};
+  const allow = Array.isArray(permissions.allow)
+    ? (permissions.allow as unknown[]).filter((e): e is string => typeof e === 'string')
+    : [];
+  return {
+    missing: findMissingEntries(allow),
+    allowList: allow,
+  };
+}
+
+// ============================================================
+// checkPermissionsDrift (extended diagnostic)
+// ============================================================
+
+/**
+ * Known-bad top-level setting keys that look like permission settings but
+ * are NOT documented at code.claude.com/docs/en/settings. Reports as
+ * `drift[unknown-key]`. Conservative list: only flags strings that are
+ * clearly typo-equivalents of documented keys or that have been observed
+ * in the wild causing confusion.
+ */
+const KNOWN_UNKNOWN_KEYS = new Set<string>([
+  // From operator's observed ~/.claude/settings.json: top-level key that is
+  // NOT in the docs (looks like a typo/wishful-thinking of skipDangerousModePermissionPrompt).
+  'skipAutoPermissionPrompt',
+]);
+
+export function checkPermissionsDrift(
+  claudeDir: string,
+  opts: { global?: Record<string, unknown> } = {},
+): { driftItems: DriftItem[] } {
+  const global = opts.global ?? readGlobalSettings();
+  const local = readSettingsLocal(claudeDir);
+  const items: DriftItem[] = [];
+
+  // (a) missing-allow
+  const localPerm = (local.permissions as Record<string, unknown> | undefined) ?? {};
+  const allow = Array.isArray(localPerm.allow)
+    ? (localPerm.allow as unknown[]).filter((e): e is string => typeof e === 'string')
+    : [];
+  const missing = findMissingEntries(allow);
+  for (const entry of missing) {
+    items.push({
+      kind: 'missing-allow',
+      detail: `Canonical massu allowlist entry missing from permissions.allow: "${entry}"`,
+      remediation: 'Run `npx massu permissions install` to seed.',
+    });
+  }
+
+  // (b) invalid-default-mode
+  const invalidMode = detectInvalidDefaultMode(local);
+  if (invalidMode.invalid && invalidMode.mode) {
+    items.push({
+      kind: 'invalid-default-mode',
+      detail: `defaultMode "${invalidMode.mode}" requires --permission-mode launch flag per code.claude.com/docs/en/permission-modes — settings-file value alone is inert.`,
+      remediation:
+        `Launch with --permission-mode ${invalidMode.mode} OR change defaultMode to one of {default, acceptEdits, plan}.`,
+    });
+  }
+
+  // (c) strips-global-defaultmode (v3 — the F15+F16 trap)
+  const globalPerm = (global.permissions as { defaultMode?: unknown } | undefined) ?? {};
+  const localHasPermissions =
+    local.permissions !== undefined && local.permissions !== null && typeof local.permissions === 'object';
+  const localHasDefaultMode = typeof (localPerm as { defaultMode?: unknown }).defaultMode === 'string';
+  const globalHasDefaultMode = typeof globalPerm.defaultMode === 'string';
+  if (localHasPermissions && !localHasDefaultMode && globalHasDefaultMode) {
+    items.push({
+      kind: 'strips-global-defaultmode',
+      detail:
+        `Project-local permissions object omits defaultMode while global ~/.claude/settings.json has ` +
+        `defaultMode="${globalPerm.defaultMode as string}". Per empirical observation (2026-05-14) the ` +
+        `merge unit is the entire permissions object, so the global defaultMode is silently stripped.`,
+      remediation:
+        'Run `npx massu permissions install` to write the full merged permissions block (auto-propagates global defaultMode).',
+    });
+  }
+
+  // (d) unknown-key (top-level only)
+  for (const key of Object.keys(local)) {
+    if (KNOWN_UNKNOWN_KEYS.has(key)) {
+      items.push({
+        kind: 'unknown-key',
+        detail: `Top-level settings key "${key}" is not documented at code.claude.com/docs/en/settings — silently ignored by Claude Code.`,
+        remediation: `Remove or replace with a documented key (e.g. skipDangerousModePermissionPrompt).`,
+      });
+    }
+  }
+
+  return { driftItems: items };
+}
+
+// Suppress unused-import warning: getConfig is imported for future use (e.g.,
+// resolving config.conventions.claudeDirName from a higher-level caller).
+void getConfig;

package/src/security/registry-pubkey.generated.ts

@@ -1,4 +1,4 @@
-// AUTO-GENERATED by scripts/bundle-pubkey.mjs at 2026-05-12T04:00:39.397Z.
+// AUTO-GENERATED by scripts/bundle-pubkey.mjs at 2026-05-15T03:59:04.298Z.
 // Source pem: packages/core/security/registry-pubkey.pem
 // RAW-bytes sha256: 3b6226d036c472e533110d11a7d0cd2773ce1d7d4f1003517d5bd69c5418ed4c
 // DO NOT EDIT — regenerate via `node scripts/bundle-pubkey.mjs` or