@pennyfarthing/core 11.2.1 → 11.3.1

package/packages/core/dist/cli/commands/doctor.js

@@ -12,8 +12,35 @@ import { findNodeModulesPath } from '../utils/node-modules.js';
 import { ALL_SYMLINKS, CORE_AGENTS } from '../utils/constants.js';
 import { getPfVersion, installPfCli } from '../utils/python.js';
 import { LEGACY_HOOK_MIGRATIONS, migrateHookPaths } from '../utils/settings.js';
+/**
+ * Category-to-check-function mapping for --category filtering.
+ * Each category maps to the check functions that produce results in that group.
+ */
+export const CATEGORY_CHECKS = {
+    'installation': ['checkInstallation', 'checkCoreFiles'],
+    'commands': ['checkCommandsAndSkills', 'checkUserFilesBasic'],
+    'hooks': ['checkSettingsHooks'],
+    'scripts': ['checkHooks', 'checkGitHooks'],
+    'layout': ['checkDirectories', 'checkFileLayout'],
+    'legacy': ['checkLegacyFiles', 'checkLegacyStatuslinePath', 'checkLegacyHookCommands'],
+    'tools': ['checkCyclist', 'checkPfCli'],
+};
 export async function doctorCommand(options) {
     const projectRoot = process.cwd();
+    // Handle --list-categories
+    if (options.listCategories) {
+        console.log('Available check categories:');
+        for (const [name, checks] of Object.entries(CATEGORY_CHECKS)) {
+            console.log(`  ${name.padEnd(14)} ${checks.join(', ')}`);
+        }
+        return;
+    }
+    // Validate --category if provided
+    if (options.category && !CATEGORY_CHECKS[options.category]) {
+        logger.error(`Unknown category: ${options.category}`);
+        logger.info(`Available categories: ${Object.keys(CATEGORY_CHECKS).join(', ')}`);
+        process.exit(1);
+    }
     // Handle dogfood mode - run checks for framework/orchestrator development
     if (options.dogfood) {
         const dogfoodScript = join(projectRoot, 'pennyfarthing-dist/scripts/misc/doctor-dogfood.sh');
@@ -45,20 +72,58 @@ export async function doctorCommand(options) {
     logger.newline();
     // Resolve node_modules path for checks that need it
     const nodeModulesPath = findNodeModulesPath(projectRoot);
-    // Run checks
-    results.push(...checkInstallation(projectRoot, manifest));
-    results.push(...checkCoreFiles(projectRoot, manifest));
-    results.push(...checkCommandsAndSkills(projectRoot, nodeModulesPath));
-    results.push(...checkUserFiles(projectRoot));
-    results.push(...checkDirectories(projectRoot));
-    results.push(...checkHooks(projectRoot));
-    results.push(...checkGitHooks(projectRoot, nodeModulesPath));
-    results.push(...checkFileLayout(projectRoot));
-    results.push(...checkLegacyFiles(projectRoot));
-    results.push(checkLegacyStatuslinePath(projectRoot));
-    results.push(checkLegacyHookCommands(projectRoot));
-    results.push(...checkCyclist(projectRoot));
-    results.push(checkPfCli(nodeModulesPath));
+    // Determine which checks to run
+    const activeChecks = options.category
+        ? new Set(CATEGORY_CHECKS[options.category])
+        : null; // null = run all
+    // Run checks — when category is specified, only run matching subset
+    if (activeChecks) {
+        // Category-filtered run
+        if (activeChecks.has('checkInstallation'))
+            results.push(...checkInstallation(projectRoot, manifest));
+        if (activeChecks.has('checkCoreFiles'))
+            results.push(...checkCoreFiles(projectRoot, manifest));
+        if (activeChecks.has('checkCommandsAndSkills'))
+            results.push(...checkCommandsAndSkills(projectRoot, nodeModulesPath));
+        if (activeChecks.has('checkUserFilesBasic'))
+            results.push(...checkUserFilesBasic(projectRoot));
+        if (activeChecks.has('checkSettingsHooks'))
+            results.push(...checkSettingsHooks(projectRoot));
+        if (activeChecks.has('checkDirectories'))
+            results.push(...checkDirectories(projectRoot));
+        if (activeChecks.has('checkHooks'))
+            results.push(...checkHooks(projectRoot));
+        if (activeChecks.has('checkGitHooks'))
+            results.push(...checkGitHooks(projectRoot, nodeModulesPath));
+        if (activeChecks.has('checkFileLayout'))
+            results.push(...checkFileLayout(projectRoot));
+        if (activeChecks.has('checkLegacyFiles'))
+            results.push(...checkLegacyFiles(projectRoot));
+        if (activeChecks.has('checkLegacyStatuslinePath'))
+            results.push(checkLegacyStatuslinePath(projectRoot));
+        if (activeChecks.has('checkLegacyHookCommands'))
+            results.push(checkLegacyHookCommands(projectRoot));
+        if (activeChecks.has('checkCyclist'))
+            results.push(...checkCyclist(projectRoot));
+        if (activeChecks.has('checkPfCli'))
+            results.push(checkPfCli(nodeModulesPath));
+    }
+    else {
+        // Full run — original behavior
+        results.push(...checkInstallation(projectRoot, manifest));
+        results.push(...checkCoreFiles(projectRoot, manifest));
+        results.push(...checkCommandsAndSkills(projectRoot, nodeModulesPath));
+        results.push(...checkUserFiles(projectRoot));
+        results.push(...checkDirectories(projectRoot));
+        results.push(...checkHooks(projectRoot));
+        results.push(...checkGitHooks(projectRoot, nodeModulesPath));
+        results.push(...checkFileLayout(projectRoot));
+        results.push(...checkLegacyFiles(projectRoot));
+        results.push(checkLegacyStatuslinePath(projectRoot));
+        results.push(checkLegacyHookCommands(projectRoot));
+        results.push(...checkCyclist(projectRoot));
+        results.push(checkPfCli(nodeModulesPath));
+    }
     // Output results
     if (options.json) {
         console.log(JSON.stringify(results, null, 2));
@@ -124,7 +189,7 @@ export async function doctorCommand(options) {
         process.exit(1);
     }
 }
-function checkInstallation(projectRoot, manifest) {
+export function checkInstallation(projectRoot, manifest) {
     const results = [];
     // Check manifest exists
     results.push({
@@ -134,7 +199,7 @@ function checkInstallation(projectRoot, manifest) {
     });
     return results;
 }
-function checkCoreFiles(projectRoot, manifest) {
+export function checkCoreFiles(projectRoot, manifest) {
     const results = [];
     const installationType = manifest?.installationType || 'copy';
     const nodeModulesPath = findNodeModulesPath(projectRoot);
@@ -196,7 +261,7 @@ function checkCoreFiles(projectRoot, manifest) {
  * Check commands and skills are properly copied (not symlinked) and up to date.
  * Commands and skills are file copies since v11.3.0 to avoid node_modules drift.
  */
-function checkCommandsAndSkills(projectRoot, nodeModulesPath) {
+export function checkCommandsAndSkills(projectRoot, _nodeModulesPath) {
     const results = [];
     // Use assetsPath for source resolution (correct pf-* prefix in dogfood)
     let assetsPath = null;
@@ -480,6 +545,91 @@ function checkSymlinks(projectRoot, nodeModulesPath) {
     }
     return results;
 }
+/**
+ * Check basic user files only (project dir, sidecars, persona config, settings.local.json existence).
+ * Does NOT include the settings hook checks — use checkSettingsHooks() for those.
+ * Used by --category commands to separate user file checks from hook configuration checks.
+ */
+export function checkUserFilesBasic(projectRoot) {
+    const results = [];
+    const manifest = readManifest(projectRoot);
+    const installationType = manifest?.installationType || 'copy';
+    // Check project directory
+    const projectDir = join(projectRoot, '.claude/project');
+    results.push({
+        name: 'project/directory',
+        status: pathExists(projectDir) ? 'pass' : 'warn',
+        detail: pathExists(projectDir) ? undefined : 'Run init to create'
+    });
+    // Check agent sidecars (now in .pennyfarthing/sidecars/)
+    const sidecarsDir = join(projectRoot, '.pennyfarthing/sidecars');
+    if (pathExists(sidecarsDir)) {
+        const existingSidecars = CORE_AGENTS.filter(a => pathExists(join(sidecarsDir, a)));
+        results.push({
+            name: 'project/sidecars',
+            status: existingSidecars.length > 0 ? 'pass' : 'warn',
+            detail: `${existingSidecars.length} agent sidecars configured`
+        });
+    }
+    // Check persona config at canonical location
+    const personaConfig = join(projectRoot, '.pennyfarthing/config.local.yaml');
+    results.push({
+        name: 'persona-config',
+        status: pathExists(personaConfig) ? 'pass' : 'warn',
+        detail: pathExists(personaConfig) ? undefined : 'No theme configured'
+    });
+    // Check settings.local.json exists (CRITICAL - registers hooks with Claude Code)
+    const settingsLocal = join(projectRoot, '.claude/settings.local.json');
+    if (!pathExists(settingsLocal)) {
+        results.push({
+            name: 'settings.local.json',
+            status: 'fail',
+            detail: 'Missing - hooks not registered with Claude Code!',
+            fix: () => {
+                createSettingsLocalJson(projectRoot, installationType);
+            }
+        });
+    }
+    else {
+        results.push({
+            name: 'settings.local.json',
+            status: 'pass',
+            detail: undefined
+        });
+    }
+    return results;
+}
+/**
+ * Check all settings hook configurations in settings.local.json.
+ * Returns results for all 9 hook checks (session-start, otel, auto-load-sm,
+ * stop, post-tool-use, benchmark-permissions, context-circuit-breaker,
+ * schema-validation, sprint-yaml-validation).
+ * Used by --category hooks for targeted hook configuration checking.
+ */
+export function checkSettingsHooks(projectRoot) {
+    const results = [];
+    const manifest = readManifest(projectRoot);
+    const installationType = manifest?.installationType || 'copy';
+    const settingsLocal = join(projectRoot, '.claude/settings.local.json');
+    if (!pathExists(settingsLocal)) {
+        results.push({
+            name: 'settings.local.json',
+            status: 'fail',
+            detail: 'Missing - cannot check hook configuration'
+        });
+        return results;
+    }
+    results.push(checkSessionStartHooks(projectRoot, installationType));
+    results.push(checkOtelAutoStart(projectRoot, installationType));
+    results.push(checkAutoLoadSmHook(projectRoot));
+    results.push(checkStopHook(projectRoot, installationType));
+    results.push(checkPostToolUseHook(projectRoot, installationType));
+    results.push(checkBenchmarkPermissions(projectRoot));
+    results.push(checkContextCircuitBreaker(projectRoot, installationType));
+    results.push(checkSchemaValidationHook(projectRoot, installationType));
+    results.push(checkSprintYamlValidationHook(projectRoot, installationType));
+    return results;
+}
 function checkUserFiles(projectRoot) {
     const results = [];
     // Detect installation type from manifest
@@ -530,6 +680,9 @@ function checkUserFiles(projectRoot) {
         // Check SessionStart hooks are configured (critical for PROJECT_ROOT)
         const hookCheck = checkSessionStartHooks(projectRoot, installationType);
         results.push(hookCheck);
+        // Check OTEL auto-configuration (WheelHub auto-start + telemetry env vars)
+        const otelCheck = checkOtelAutoStart(projectRoot, installationType);
+        results.push(otelCheck);
         // Check auto-load-sm hook is configured (auto-invokes /sm on new sessions)
         const autoLoadSmCheck = checkAutoLoadSmHook(projectRoot);
         results.push(autoLoadSmCheck);
@@ -654,7 +807,7 @@ function checkSessionStartHooks(projectRoot, installationType) {
         const hasSessionStartHook = settings.hooks.SessionStart.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('pf hooks session-start') || h.command?.includes('session-start.sh'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks session-start') || h.command?.includes('pf hooks session-start') || h.command?.includes('session-start.sh'));
             }
             return false;
         });
@@ -682,6 +835,96 @@ function checkSessionStartHooks(projectRoot, installationType) {
         };
     }
 }
+/**
+ * Check that session-start hook uses `pf hooks session-start` (Python version)
+ * which handles WheelHub auto-start + OTEL env var configuration.
+ * Legacy .sh hooks only set 2 of 5 required OTEL vars, breaking telemetry.
+ */
+function checkOtelAutoStart(projectRoot, installationType) {
+    const settingsPath = join(projectRoot, '.claude/settings.local.json');
+    try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        if (!settings.hooks?.SessionStart) {
+            return {
+                name: 'settings/otel-auto-start',
+                status: 'warn',
+                detail: 'No SessionStart hooks — WheelHub auto-start and OTEL not configured',
+            };
+        }
+        // Check if `pf hooks session-start` is used (Python version with full OTEL support)
+        const hasPfHooksSessionStart = settings.hooks.SessionStart.some((entry) => {
+            if (typeof entry === 'object' && entry !== null) {
+                const hookEntry = entry;
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks session-start') || h.command?.includes('pf hooks session-start'));
+            }
+            return false;
+        });
+        if (hasPfHooksSessionStart) {
+            return {
+                name: 'settings/otel-auto-start',
+                status: 'pass',
+                detail: undefined,
+            };
+        }
+        // Check if using legacy .sh (only sets 2 of 5 OTEL vars)
+        const hasLegacySh = settings.hooks.SessionStart.some((entry) => {
+            if (typeof entry === 'object' && entry !== null) {
+                const hookEntry = entry;
+                return hookEntry.hooks?.some(h => h.command?.includes('session-start.sh'));
+            }
+            return false;
+        });
+        if (hasLegacySh) {
+            return {
+                name: 'settings/otel-auto-start',
+                status: 'warn',
+                detail: 'Using legacy session-start.sh — missing WheelHub auto-start and 3 OTEL env vars. Migrate to `pf hooks session-start`',
+                fix: () => {
+                    migrateSessionStartToPfHooks(projectRoot);
+                },
+            };
+        }
+        return {
+            name: 'settings/otel-auto-start',
+            status: 'warn',
+            detail: 'session-start hook not found — WheelHub auto-start and OTEL not configured',
+            fix: () => {
+                addSessionStartHooks(projectRoot, installationType);
+            },
+        };
+    }
+    catch {
+        return {
+            name: 'settings/otel-auto-start',
+            status: 'warn',
+            detail: 'Could not parse settings.local.json',
+        };
+    }
+}
+/**
+ * Migrate legacy session-start.sh hooks to `pf hooks session-start`
+ */
+function migrateSessionStartToPfHooks(projectRoot) {
+    const settingsPath = join(projectRoot, '.claude/settings.local.json');
+    try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        if (Array.isArray(settings.hooks?.SessionStart)) {
+            for (const entry of settings.hooks.SessionStart) {
+                if (typeof entry === 'object' && entry !== null && Array.isArray(entry.hooks)) {
+                    for (const h of entry.hooks) {
+                        if (h.command?.includes('session-start.sh')) {
+                            h.command = '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-start';
+                        }
+                    }
+                }
+            }
+        }
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+    }
+    catch {
+        // Silent fail — doctor will re-report on next run
+    }
+}
 /**
  * Check that auto-load-sm hook is configured in SessionStart
  * This auto-invokes /sm agent on new session start
@@ -832,7 +1075,7 @@ function checkStopHook(projectRoot, installationType) {
         const hasReflectorHook = settings.hooks.Stop.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('pf hooks reflector-check') || h.command?.includes('question-reflector-check'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks reflector-check') || h.command?.includes('pf hooks reflector-check') || h.command?.includes('question-reflector-check'));
             }
             return false;
         });
@@ -883,7 +1126,7 @@ function checkContextCircuitBreaker(projectRoot, installationType) {
         const hasCircuitBreaker = settings.hooks.PreToolUse.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('pf hooks context-breaker') || h.command?.includes('context-circuit-breaker'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks context-breaker') || h.command?.includes('pf hooks context-breaker') || h.command?.includes('context-circuit-breaker'));
             }
             return false;
         });
@@ -921,7 +1164,7 @@ function addContextCircuitBreaker(projectRoot, _installationType) {
         hooks: [
             {
                 type: 'command',
-                command: 'pf hooks context-breaker'
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks context-breaker'
             }
         ]
     };
@@ -1009,7 +1252,7 @@ function addSchemaValidationHook(projectRoot, _installationType) {
         hooks: [
             {
                 type: 'command',
-                command: 'pf hooks schema-validation'
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks schema-validation'
             }
         ]
     };
@@ -1059,7 +1302,7 @@ function checkPostToolUseHook(projectRoot, installationType) {
         const hasBellModeHook = settings.hooks.PostToolUse.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('pf hooks bell-mode') || h.command?.includes('bell-mode-hook'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks bell-mode') || h.command?.includes('pf hooks bell-mode') || h.command?.includes('bell-mode-hook'));
             }
             return false;
         });
@@ -1098,7 +1341,7 @@ function addPostToolUseHook(projectRoot, _installationType) {
         hooks: [
             {
                 type: 'command',
-                command: 'pf hooks bell-mode'
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks bell-mode'
             }
         ]
     };
@@ -1148,7 +1391,7 @@ function checkSprintYamlValidationHook(projectRoot, installationType) {
         const hasSprintYamlValidation = settings.hooks.PostToolUse.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('pf hooks sprint-yaml') || h.command?.includes('sprint-yaml-validation'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks sprint-yaml') || h.command?.includes('pf hooks sprint-yaml') || h.command?.includes('sprint-yaml-validation'));
             }
             return false;
         });
@@ -1187,7 +1430,7 @@ function addSprintYamlValidationHook(projectRoot, _installationType) {
         hooks: [
             {
                 type: 'command',
-                command: 'pf hooks sprint-yaml'
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks sprint-yaml'
             }
         ]
     };
@@ -1225,7 +1468,7 @@ function addStopHook(projectRoot, _installationType) {
             hooks: [
                 {
                     type: 'command',
-                    command: 'pf hooks reflector-check'
+                    command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks reflector-check'
                 }
             ]
         },
@@ -1234,7 +1477,7 @@ function addStopHook(projectRoot, _installationType) {
             hooks: [
                 {
                     type: 'command',
-                    command: 'pf hooks session-stop'
+                    command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-stop'
                 }
             ]
         }
@@ -1282,7 +1525,7 @@ function addSessionStartHooks(projectRoot, _installationType) {
             hooks: [
                 {
                     type: 'command',
-                    command: 'pf hooks session-start'
+                    command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-start'
                 }
             ]
         },
@@ -1376,7 +1619,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks session-start'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-start'
                         }
                     ]
                 },
@@ -1404,7 +1647,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks reflector-check'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks reflector-check'
                         }
                     ]
                 },
@@ -1413,7 +1656,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks session-stop'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-stop'
                         }
                     ]
                 }
@@ -1424,7 +1667,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks bell-mode'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks bell-mode'
                         }
                     ]
                 },
@@ -1433,7 +1676,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks sprint-yaml'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks sprint-yaml'
                         }
                     ]
                 }
@@ -1444,7 +1687,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks pre-edit-check'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks pre-edit-check'
                         }
                     ]
                 },
@@ -1453,7 +1696,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks schema-validation'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks schema-validation'
                         }
                     ]
                 },
@@ -1462,7 +1705,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks context-warning'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks context-warning'
                         }
                     ]
                 },
@@ -1471,7 +1714,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks context-breaker'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks context-breaker'
                         }
                     ]
                 },
@@ -1479,7 +1722,7 @@ function createSettingsLocalJson(projectRoot, _installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: 'pf hooks cyclist-pretooluse'
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks cyclist-pretooluse'
                         }
                     ]
                 }
@@ -1487,13 +1730,13 @@ function createSettingsLocalJson(projectRoot, _installationType) {
         },
         statusLine: {
             type: 'command',
-            command: 'pf hooks statusline'
+            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks statusline'
         }
     };
     ensureDirSync(join(projectRoot, '.claude'));
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
 }
-function checkDirectories(projectRoot) {
+export function checkDirectories(projectRoot) {
     const results = [];
     const dirs = [
         { path: 'sprint', name: 'dir/sprint' },
@@ -1509,7 +1752,7 @@ function checkDirectories(projectRoot) {
     }
     return results;
 }
-function checkHooks(projectRoot) {
+export function checkHooks(projectRoot) {
     const results = [];
     // Detect installation type from manifest
     const manifest = readManifest(projectRoot);
@@ -1566,7 +1809,7 @@ function checkHooks(projectRoot) {
  * symlinked rather than copied, since symlinks stay current automatically.
  * Provides --fix to refresh stale hooks or replace copies with symlinks.
  */
-function checkGitHooks(projectRoot, nodeModulesPath) {
+export function checkGitHooks(projectRoot, nodeModulesPath) {
     const results = [];
     // Use git rev-parse to find the actual git dir (handles worktrees where .git is a file)
     const gitDirResult = spawnSync('git', ['rev-parse', '--git-dir'], { cwd: projectRoot, encoding: 'utf8' });
@@ -1710,7 +1953,7 @@ function checkGitHooks(projectRoot, nodeModulesPath) {
  * Check Cyclist installation health (if installed as a workspace package)
  * Detects node-pty spawn-helper permission issues that cause posix_spawnp failures
  */
-function checkCyclist(projectRoot) {
+export function checkCyclist(projectRoot) {
     const results = [];
     // Detect Cyclist package — check common locations
     const cyclistLocations = [
@@ -1812,7 +2055,7 @@ function checkCyclist(projectRoot) {
  * Check if the pf CLI is installed and working.
  * The pf CLI is required for agent commands (e.g., `pf agent start "dev"`).
  */
-function checkPfCli(nodeModulesPath) {
+export function checkPfCli(nodeModulesPath) {
     const version = getPfVersion();
     if (version) {
         return {
@@ -2049,7 +2292,7 @@ export function checkLegacyStatuslinePath(projectRoot) {
     const pathMatch = command.match(/(?:\"\$CLAUDE_PROJECT_DIR\"\/)?([^\s"]+)/);
     const currentPath = pathMatch ? pathMatch[1] : command;
     // Check if it's the canonical pf hooks command or the legacy .sh path
-    if (command === 'pf hooks statusline' || currentPath.includes('misc/statusline.sh') || command.includes('misc/statusline.sh')) {
+    if (command.includes('pf.sh hooks statusline') || command === 'pf hooks statusline' || currentPath.includes('misc/statusline.sh') || command.includes('misc/statusline.sh')) {
         return {
             name: 'settings/statusline-path',
             status: 'pass',
@@ -2070,7 +2313,7 @@ export function checkLegacyStatuslinePath(projectRoot) {
                     const updatedSettings = { ...settings };
                     updatedSettings.statusLine = {
                         type: 'command',
-                        command: 'pf hooks statusline'
+                        command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks statusline'
                     };
                     writeFileSync(settingsPath, JSON.stringify(updatedSettings, null, 2));
                 }
@@ -2089,7 +2332,7 @@ export function checkLegacyStatuslinePath(projectRoot) {
  * be migrated to `pf hooks` commands. The .sh scripts still work (they're shims)
  * but `pf hooks` is the canonical path — faster, no shell indirection.
  */
-function checkLegacyHookCommands(projectRoot) {
+export function checkLegacyHookCommands(projectRoot) {
     const settingsPath = join(projectRoot, '.claude/settings.local.json');
     if (!pathExists(settingsPath)) {
         return { name: 'legacy/hook-commands', status: 'pass', detail: 'No settings file' };
@@ -2126,7 +2369,7 @@ function checkLegacyHookCommands(projectRoot) {
     }
     // Also check statusLine
     const statusLine = settings.statusLine;
-    if (statusLine?.command && statusLine.command !== 'pf hooks statusline') {
+    if (statusLine?.command && !statusLine.command.includes('pf.sh hooks statusline') && statusLine.command !== 'pf hooks statusline') {
         for (const shName of Object.keys(LEGACY_HOOK_MIGRATIONS)) {
             if (statusLine.command.includes(shName)) {
                 legacyCount++;
@@ -2148,7 +2391,7 @@ function checkLegacyHookCommands(projectRoot) {
                 }
             }
             // Migrate statusLine
-            if (statusLine?.command && statusLine.command !== 'pf hooks statusline') {
+            if (statusLine?.command && !statusLine.command.includes('pf.sh hooks statusline') && statusLine.command !== 'pf hooks statusline') {
                 for (const [shName, pfCommand] of Object.entries(LEGACY_HOOK_MIGRATIONS)) {
                     if (statusLine.command.includes(shName)) {
                         statusLine.command = pfCommand;
@@ -2261,6 +2504,26 @@ export function checkFileLayout(projectRoot) {
             status: 'pass',
             detail: undefined
         });
+        // Check execute permission on each shell script in project hooks
+        try {
+            const hookFiles = readdirSync(projectHooksPath).filter(f => f.endsWith('.sh'));
+            for (const file of hookFiles) {
+                const hookPath = join(projectHooksPath, file);
+                const stats = statSync(hookPath);
+                const isExecutable = (stats.mode & 0o111) !== 0;
+                results.push({
+                    name: `layout/project-hooks/${file}`,
+                    status: isExecutable ? 'pass' : 'warn',
+                    detail: isExecutable ? undefined : 'Not executable — will cause Permission denied on session start',
+                    fix: isExecutable ? undefined : () => {
+                        chmodSync(hookPath, 0o755);
+                    }
+                });
+            }
+        }
+        catch {
+            // Ignore read errors
+        }
     }
     // 8. Old project hooks at .claude/project/hooks/
     const oldProjectHooksPath = join(projectRoot, '.claude/project/hooks');
@@ -2290,6 +2553,17 @@ export function checkFileLayout(projectRoot) {
                     }
                     removeSync(oldProjectHooksPath);
                 }
+                // Ensure migrated shell scripts are executable
+                try {
+                    for (const file of readdirSync(projectHooksPath)) {
+                        if (file.endsWith('.sh')) {
+                            chmodSync(join(projectHooksPath, file), 0o755);
+                        }
+                    }
+                }
+                catch {
+                    // Ignore
+                }
             }
         });
     }