@north-light/api 0.3.580 → 0.3.588

package/dist/commands/sys/doctor.d.ts

@@ -0,0 +1,36 @@
+import { type Scope } from '../../types.js';
+type CheckStatus = 'pass' | 'fail';
+type CheckScope = Scope | 'canvas';
+/**
+ * Structured fix action for a failing check. Surfaced on each
+ * non-pass result so an agent reading doctor output can apply it directly
+ * when `--fix` is not used (or when --fix did not auto-apply). Every
+ * remediation includes the exact action and payload — no inference required.
+ */
+interface Remediation {
+    kind: 'remove_config_key' | 'rm_path' | 'human_action';
+    description: string;
+    scope?: Scope;
+    configKey?: string;
+    path?: string;
+    command?: string;
+}
+interface CheckResult {
+    scope: CheckScope;
+    name: string;
+    status: CheckStatus;
+    message: string;
+    fixed?: boolean;
+    remediation?: Remediation;
+}
+/**
+ * Validate the command manifest + executable path of every effective command
+ * plugin (the deduped, enabled set that actually composes into the tree).
+ * Purely static — the plugin binary is NEVER executed, and no remediation ever
+ * chmods or rewrites third-party plugin content (every fix is a human_action:
+ * disable/update/remove the plugin). Only plugins whose scope is in `scopes`
+ * are reported, so `--scope` narrows these checks too.
+ */
+export declare function runCommandPluginChecks(scopes: Scope[]): Promise<CheckResult[]>;
+export declare const sysDoctorLeaf: import("../../core/command.js").LeafDef;
+export {};

package/dist/commands/sys/doctor.js

@@ -0,0 +1,633 @@
+import { envGrantee, envProfileId } from '../../shared/env.js';
+import { requiredPluginEnv } from '../../core/plugin-env.js';
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readdir, readlink } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { normalizeRequires, readConfig, updateConfig } from '../../core/config.js';
+import { scopeRoot, listScopes, marketplacesDir, pluginsDir } from '../../core/scope.js';
+import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
+import { pathExists, listDirs, removePath } from '../../core/fs-utils.js';
+import { lsRemote } from '../../core/git.js';
+import { cliClient } from '../api-client.js';
+import { detectNerdFont, nerdFontInstallCommand, NERD_FONT_SELECT_HINT } from '../../core/runtime/nerd-font.js';
+import { detectPackageManager } from './setup-core.js';
+import { validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { adaptPluginContributions } from '../../core/command-plugins/compose.js';
+import { resolveCommandRegistry } from '../../core/command-manifests/registry.js';
+import { applyCommandExtensions, orphanCommandExtensionValidations } from '../../core/command-plugins/extensions.js';
+import { discoverHookRegistry } from '../../core/command-hooks/discovery.js';
+import { resolveBinContributions } from '../../core/runtime/bin-contributions.js';
+import { inspectHumanActions } from '../../core/human-actions.js';
+import { composeAppProcessEnv, overlayBrokerEnv, resolvePathExecutable } from '../../core/runtime/spawn-env.js';
+import { listAllPlugins } from '../../core/resolver.js';
+import { SUBTREE_NAMES, coreCommandPaths, coreHookCatalog, extensibleCoreBranches } from '../../build-root.js';
+import { processGeneration, processLocatedGeneration, runtimeManifest, selectedGeneration } from './shared.js';
+import { CONFIG_FILE } from '../../types.js';
+function pass(scope, name, message) {
+    return { scope, name, status: 'pass', message };
+}
+function failCheck(scope, name, message, remediation) {
+    return { scope, name, status: 'fail', message, ...(remediation ? { remediation } : {}) };
+}
+/**
+ * Apply a remediation. Returns true if applied successfully. Idempotent for
+ * the supported kinds (re-applying a config-key removal that's already gone
+ * returns true).
+ */
+async function applyRemediation(rem) {
+    try {
+        switch (rem.kind) {
+            case 'remove_config_key': {
+                if (!rem.scope || !rem.configKey)
+                    return false;
+                const segments = rem.configKey.split('.');
+                await updateConfig(rem.scope, (c) => {
+                    let cursor = c;
+                    for (let i = 0; i < segments.length - 1; i++) {
+                        const next = cursor[segments[i]];
+                        if (typeof next !== 'object' || next === null)
+                            return;
+                        cursor = next;
+                    }
+                    delete cursor[segments[segments.length - 1]];
+                });
+                return true;
+            }
+            case 'rm_path': {
+                if (!rem.path)
+                    return false;
+                removePath(rem.path);
+                return true;
+            }
+            case 'human_action':
+                return false;
+            default:
+                return false;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+function faultMessage(fault) {
+    const parts = [
+        `${fault.link} ${fault.kind}`,
+        `disposition=${fault.retry.disposition}`,
+        typeof fault.retry.attempt === 'number' && typeof fault.retry.max === 'number' ? `attempt=${fault.retry.attempt}/${fault.retry.max}` : undefined,
+        typeof fault.retry.nextAt === 'string' ? `nextAt=${fault.retry.nextAt}` : undefined,
+    ].filter((part) => part !== undefined);
+    return parts.join(' · ');
+}
+function shellArgument(value) {
+    return /^[A-Za-z0-9._:/@%+=,-]+$/u.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+function faultRemediation(fault, nodeId) {
+    const actionByKind = {
+        connection: 'restore connectivity',
+        'rate-limit': 'wait for the rate limit to clear',
+        overloaded: 'wait for load to drop',
+        auth: 're-authenticate',
+        protocol: 'fix the protocol mismatch',
+        'context-overflow': 'shrink the task or loaded context, or choose a larger-context model before spawning the node again',
+        other: 'fix the underlying issue',
+        wedged: 'read `crtr canvas read wedged-child-on-runaway-bash` — if a runaway subprocess is to blame, kill it (not the node); if the broker had no subprocess, the daemon SIGTERM-kicks it and starts a fresh recovery cycle automatically',
+        'model-not-found': 'pass a valid `--model provider/id` or configure credentials for an authenticated provider, then revive the node (`crtr node lifecycle revive <id>`)',
+    };
+    const progress = fault.retry.disposition === 'auto'
+        ? fault.retry.by === 'client'
+            ? 'client redialing'
+            : typeof fault.retry.attempt === 'number' && typeof fault.retry.max === 'number'
+                ? `auto-retrying, attempt ${fault.retry.attempt}/${fault.retry.max}`
+                : 'auto-retrying'
+        : fault.retry.disposition === 'fatal'
+            ? 'parked fatal'
+            : 'manual';
+    const command = `crtr sys logs --node ${shellArgument(nodeId)} --operation ${shellArgument(fault.operation_id)}`;
+    return {
+        kind: 'human_action',
+        description: `${actionByKind[fault.kind]}; ${progress}; inspect the correlated operation with ${command}`,
+        command,
+    };
+}
+/**
+ * Validate the command manifest + executable path of every effective command
+ * plugin (the deduped, enabled set that actually composes into the tree).
+ * Purely static — the plugin binary is NEVER executed, and no remediation ever
+ * chmods or rewrites third-party plugin content (every fix is a human_action:
+ * disable/update/remove the plugin). Only plugins whose scope is in `scopes`
+ * are reported, so `--scope` narrows these checks too.
+ */
+export async function runCommandPluginChecks(scopes) {
+    const results = [];
+    const inScope = new Set(scopes);
+    const reserved = new Set(SUBTREE_NAMES);
+    // Validate the whole effective set together so cross-plugin top-level name
+    // collisions surface here. A collision no longer costs anyone their command:
+    // each claimant mounts under an origin-qualified name, so it is reported as a
+    // healthy mount rather than a failure demanding the user remove a plugin.
+    const [corePaths, extensibleBranches] = await Promise.all([coreCommandPaths(), extensibleCoreBranches()]);
+    const validations = validateEffectiveCommandPlugins(reserved, undefined, undefined, corePaths, extensibleBranches);
+    for (const v of validations) {
+        const plugin = v.plugin;
+        if (!inScope.has(plugin.scope))
+            continue;
+        const blocking = v.issues.filter((issue) => issue.code !== 'command_collision');
+        if (blocking.length === 0) {
+            const mounts = v.contributions.map((c) => c.node.name).join(', ');
+            results.push(pass(plugin.scope, `plugin:${plugin.name}:commands`, mounts.length > 0 ? `contributes top-level command(s): ${mounts}` : `command manifest valid`));
+            continue;
+        }
+        blocking.forEach((issue, i) => {
+            const remediation = {
+                kind: 'human_action',
+                description: `${issue.next} Inspect with \`pkg plugin show ${plugin.name}\`; then update (\`pkg plugin update --name ${plugin.name}\`) or remove (\`pkg plugin remove ${plugin.name}\`) the plugin.`,
+            };
+            const detail = issue.path !== undefined ? ` at ${issue.path}` : '';
+            results.push(failCheck(plugin.scope, `plugin:${plugin.name}:commands[${i}]`, `${issue.code}${detail}: ${issue.message} (received ${issue.received}, expected ${issue.expected})`, remediation));
+        });
+    }
+    if (inScope.has('project')) {
+        const registry = resolveCommandRegistry(adaptPluginContributions(validations.flatMap((validation) => validation.contributions)).contributions, reserved);
+        const extensions = applyCommandExtensions(registry.contributions);
+        const allExtensionChecks = [...extensions.validations, ...orphanCommandExtensionValidations(registry.contributions)];
+        for (const extension of allExtensionChecks) {
+            if (extension.issue === undefined) {
+                results.push(pass('project', `extension:${extension.branch}`, `repository fragment valid: ${extension.fragmentPath}`));
+                continue;
+            }
+            const issue = extension.issue;
+            results.push(failCheck('project', `extension:${extension.branch}`, `${issue.code} at ${issue.path ?? extension.fragmentPath}: ${issue.message} (received ${issue.received}, expected ${issue.expected})`, {
+                kind: 'human_action',
+                description: issue.next,
+            }));
+        }
+    }
+    return results;
+}
+/** Statically inspect the complete effective hook registry. This shares the
+ * runtime target catalog but never enters hook execution, preserving doctor as
+ * the recovery path for broken hooks. */
+async function runHookPluginChecks(scopes) {
+    const inScope = new Set(scopes);
+    const registry = discoverHookRegistry(await coreHookCatalog());
+    const results = [];
+    for (const validation of registry.validations) {
+        const plugin = validation.plugin;
+        if (!inScope.has(plugin.scope))
+            continue;
+        const issues = registry.issues.filter((issue) => issue.plugin === plugin.name && issue.scope === plugin.scope);
+        if (issues.length === 0) {
+            const commandDeclarations = validation.hooks.map((hook) => `${hook.target} [${hook.phase} ${hook.op}]`);
+            const lifecycleDeclarations = (validation.manifest?.schemaVersion === 2 ? validation.manifest.lifecycle : []).map((hook) => `${hook.event} [${hook.phase} ${hook.op}; effects: ${hook.effects.join(', ')}]`);
+            results.push(pass(plugin.scope, `plugin:${plugin.name}:hooks`, `effective hook declaration(s): ${[...commandDeclarations, ...lifecycleDeclarations].join('; ')}`));
+            continue;
+        }
+        issues.forEach((issue, index) => {
+            const source = validation.manifestPath ?? join(plugin.root, '.crouter-plugin', 'plugin.json');
+            const detail = issue.path !== undefined ? `${source}:${issue.path}` : source;
+            results.push(failCheck(plugin.scope, `plugin:${plugin.name}:hooks[${index}]`, `${issue.code} at ${detail}: ${issue.message} (received ${issue.received}, expected ${issue.expected})`, {
+                kind: 'human_action',
+                description: `${issue.next} Inspect with \`crtr pkg plugin show ${plugin.name}\`; then disable (\`crtr pkg plugin disable ${plugin.name} --scope ${plugin.scope}\`), update (\`crtr pkg plugin update --name ${plugin.name}\`), or remove (\`crtr pkg plugin remove ${plugin.name}\`) the plugin.`,
+            }));
+        });
+    }
+    return results;
+}
+/**
+ * Report every bare-binary contribution (`bin` in a plugin manifest or a scope
+ * `config.json`) that failed to reach a node's PATH, plus the ones that did.
+ * Purely static — the declared executable is NEVER run, exactly as plugin
+ * command manifests are only ever validated. Every remediation is a
+ * human_action: fixing a contributor's declaration or its file is the owner's
+ * call, never doctor's. Only contributions from a scope in `scopes` are
+ * reported, so `--scope` narrows these checks too.
+ */
+function runBinContributionChecks(scopes) {
+    const inScope = new Set(scopes);
+    const { bins, issues } = resolveBinContributions(process.cwd(), envProfileId() || null);
+    const results = [];
+    for (const issue of issues) {
+        if (!inScope.has(issue.scope))
+            continue;
+        results.push(failCheck(issue.scope, `bin:${issue.name}`, `${issue.origin}: ${issue.message}`, {
+            kind: 'human_action',
+            description: `Fix the \`bin.${issue.name}\` declaration in ${issue.origin} — point it at an executable regular file inside that contributor's own root, or remove it. A same-precedence collision is resolved by renaming one of the claimants.`,
+        }));
+    }
+    for (const bin of bins.values()) {
+        if (!inScope.has(bin.scope))
+            continue;
+        results.push(pass(bin.scope, `bin:${bin.name}`, `${bin.origin} → ${bin.target}`));
+    }
+    return results;
+}
+/** Validate every scope-configured completion action without executing it. */
+function runHumanActionChecks(scopes) {
+    const inScope = new Set(scopes);
+    const userConfig = join(scopeRoot('user'), CONFIG_FILE);
+    const results = [];
+    const winningOrigins = new Map();
+    for (const action of inspectHumanActions(process.cwd())) {
+        if ('kind' in action) {
+            if (action.kind === 'unknown_action')
+                continue;
+            const scope = action.configOrigin === userConfig ? 'user' : 'project';
+            const block = action.block === true;
+            const winningOrigin = block ? undefined : winningOrigins.get(action.name);
+            if (!block && winningOrigin === undefined)
+                winningOrigins.set(action.name, action.configOrigin);
+            if (!inScope.has(scope))
+                continue;
+            const checkName = block ? `humanActions:block@${action.configOrigin}` : `humanActions:${action.name}@${action.configOrigin}`;
+            const remediation = {
+                kind: 'human_action',
+                description: block
+                    ? `Fix or remove the \`humanActions\` block in ${action.configOrigin}. Actions run argv directly without a shell.`
+                    : `Fix or remove the \`humanActions.${action.name}\` declaration in ${action.configOrigin}. Actions run argv directly without a shell.`,
+            };
+            if (winningOrigin !== undefined) {
+                results.push({
+                    scope,
+                    name: checkName,
+                    status: 'pass',
+                    message: `warning: shadowed by ${winningOrigin}; ${action.configOrigin}: ${action.reason}`,
+                    remediation,
+                });
+            }
+            else {
+                results.push(failCheck(scope, checkName, `${action.configOrigin}: ${action.reason}`, remediation));
+            }
+            continue;
+        }
+        const scope = action.configOrigin === userConfig ? 'user' : 'project';
+        const winningOrigin = winningOrigins.get(action.name);
+        if (winningOrigin === undefined)
+            winningOrigins.set(action.name, action.configOrigin);
+        if (!inScope.has(scope))
+            continue;
+        const shadowedPrefix = winningOrigin === undefined ? '' : `shadowed by ${winningOrigin}; `;
+        results.push(pass(scope, `humanActions:${action.name}@${action.configOrigin}`, `${shadowedPrefix}${action.configOrigin} → ${action.argv[0]} (cwd ${action.cwd})`));
+    }
+    return results;
+}
+/** Check each enabled plugin's advisory PATH requirements against the exact
+ *  broker environment a node launched from this cwd/profile receives. */
+async function runRequiresChecks(scopes) {
+    const inScope = new Set(scopes);
+    // The check needs PATH and which names are set, never a value: stored names stand in as empty strings.
+    const profileId = envProfileId() ?? null;
+    const app = envGrantee() ?? 'app:terminal';
+    const client = cliClient();
+    const present = (names) => Object.fromEntries(names.map((name) => [name, '']));
+    const env = overlayBrokerEnv({ argv: [], env: { CRTR_NODE_CWD: process.cwd(), CRTR_PROFILE_ID: profileId ?? '', CRTR_GRANTEE: app } }, composeAppProcessEnv(process.cwd(), profileId, app, present((await client.listAppEnv()).names), profileId === null ? {} : present((await client.listProfileEnv(profileId)).names)));
+    const results = [];
+    for (const plugin of listAllPlugins()) {
+        if (!inScope.has(plugin.scope) || !plugin.enabled)
+            continue;
+        for (const name of requiredPluginEnv(plugin.manifest.env)) {
+            if (env[name] !== undefined)
+                results.push(pass(plugin.scope, `env:${name}`, `plugin "${plugin.name}" has ${name}`));
+            else
+                results.push(failCheck(plugin.scope, `env:${name}`, `plugin "${plugin.name}" needs ${name}`, {
+                    kind: 'human_action', description: `crtr sys env set --name ${name}`,
+                }));
+        }
+        if (plugin.manifest.requires === undefined)
+            continue;
+        for (const [name, hint] of Object.entries(normalizeRequires(plugin.manifest.requires))) {
+            const target = resolvePathExecutable(name, env, process.cwd());
+            if (target !== null) {
+                results.push(pass(plugin.scope, `requires:${name}`, `plugin "${plugin.name}" → ${target}`));
+            }
+            else {
+                results.push(failCheck(plugin.scope, `requires:${name}`, `plugin "${plugin.name}" requires executable "${name}" on PATH`, {
+                    kind: 'human_action',
+                    description: hint,
+                }));
+            }
+        }
+    }
+    return results;
+}
+async function inventory(root) {
+    const files = [];
+    async function walk(dir) {
+        for (const name of await readdir(dir)) {
+            const absolute = join(dir, name);
+            const path = relative(root, absolute).replaceAll(sep, '/');
+            if (path === 'generation.json')
+                continue;
+            const stat = await lstat(absolute);
+            if (stat.isDirectory()) {
+                await walk(absolute);
+            }
+            else if (stat.isFile()) {
+                const content = await readFile(absolute);
+                files.push({ path, size: stat.size, sha256: createHash('sha256').update(content).digest('hex') });
+            }
+            else if (stat.isSymbolicLink()) {
+                const target = await readlink(absolute);
+                if (isAbsolute(target) || !runtimeManifest.contained(root, resolve(dirname(absolute), target))) {
+                    throw new Error(`generation symlink escapes root: ${path}`);
+                }
+                files.push({ path, size: Buffer.byteLength(target), sha256: createHash('sha256').update(target).digest('hex'), symlink: true });
+            }
+            else {
+                throw new Error(`unsupported generation file: ${path}`);
+            }
+        }
+    }
+    await walk(root);
+    return runtimeManifest.sortInventory(files);
+}
+async function verifySealed(root) {
+    async function walk(dir) {
+        const stat = await lstat(dir);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error(`generation directory is invalid: ${dir}`);
+        if ((stat.mode & 0o222) !== 0)
+            throw new Error(`generation path is writable: ${dir}`);
+        for (const name of await readdir(dir)) {
+            const path = join(dir, name);
+            const child = await lstat(path);
+            if (child.isDirectory())
+                await walk(path);
+            else if (child.isFile()) {
+                if ((child.mode & 0o222) !== 0)
+                    throw new Error(`generation path is writable: ${path}`);
+            }
+            else if (child.isSymbolicLink()) {
+                const target = await readlink(path);
+                if (isAbsolute(target) || !runtimeManifest.contained(root, resolve(dirname(path), target)))
+                    throw new Error(`generation symlink escapes root: ${path}`);
+            }
+            else
+                throw new Error(`unsupported generation file: ${path}`);
+        }
+    }
+    await walk(root);
+}
+/** The viewer draws every tool and command icon with Nerd Font codepoints, so a
+ *  machine with no Nerd Font installed renders tofu boxes. Nothing else in
+ *  crtr notices — this is the one place a fresh install learns why. Never
+ *  auto-fixed: installing a font, and pointing the terminal profile at it, is a
+ *  human action. */
+function runNerdFontCheck() {
+    const detection = detectNerdFont();
+    if (detection.installed) {
+        return pass('user', 'terminal:nerd-font', `installed (${detection.evidence}) — if icons still render as boxes, ${NERD_FONT_SELECT_HINT}`);
+    }
+    const plan = nerdFontInstallCommand(detectPackageManager());
+    return failCheck('user', 'terminal:nerd-font', 'no Nerd Font installed — viewer tool/command icons will render as tofu boxes', {
+        kind: 'human_action',
+        description: `Install a Nerd Font (${plan.hint}), ${NERD_FONT_SELECT_HINT}`,
+        ...(plan.command ? { command: plan.command } : {}),
+    });
+}
+async function generationChecks(label, lookup, allowAbsent) {
+    if (lookup.generation === null) {
+        const message = lookup.error ?? 'no runtime generation';
+        return [allowAbsent ? pass('canvas', `runtime:${label}`, message) : failCheck('canvas', `runtime:${label}`, message)];
+    }
+    const generation = lookup.generation;
+    const results = [];
+    const shape = runtimeManifest.validateManifestShape(generation.manifest, { id: generation.id, entryName: 'cli' });
+    if (!shape.ok)
+        return [failCheck('canvas', `runtime:${label}:manifest`, shape.error)];
+    results.push(pass('canvas', `runtime:${label}:manifest`, `${generation.id} ${generation.manifest.packageVersion}`));
+    try {
+        await verifySealed(generation.root);
+        results.push(pass('canvas', `runtime:${label}:sealing`, 'generation tree is sealed and contained'));
+    }
+    catch (error) {
+        results.push(failCheck('canvas', `runtime:${label}:sealing`, error instanceof Error ? error.message : String(error)));
+    }
+    try {
+        const actual = await inventory(generation.root);
+        const expected = runtimeManifest.sortInventory(generation.manifest.files);
+        if (JSON.stringify(generation.manifest.files) !== JSON.stringify(expected)) {
+            results.push(failCheck('canvas', `runtime:${label}:inventory`, 'manifest inventory is not in canonical runtime-generation-manifest order'));
+        }
+        else if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+            results.push(failCheck('canvas', `runtime:${label}:inventory`, 'full generation inventory hash does not match generation.json'));
+        }
+        else {
+            results.push(pass('canvas', `runtime:${label}:inventory`, `${actual.length} files hash-verified`));
+        }
+    }
+    catch (error) {
+        results.push(failCheck('canvas', `runtime:${label}:inventory`, error instanceof Error ? error.message : String(error)));
+    }
+    return results;
+}
+/** One failing check per node parked on an active fault. The fault is the
+ *  daemon's projection on the node summary — the stale-provider overlay (a
+ *  daemon-owned auto retry whose broker pid is gone) is already applied there,
+ *  so this leaf needs no local read. */
+async function runFaultChecks() {
+    const results = [];
+    for (const node of await cliClient().listNodes()) {
+        const fault = node.fault ?? null;
+        if (fault === null)
+            continue;
+        const name = `fault:${node.node_id}:${fault.link}`;
+        const remediation = faultRemediation(fault, node.node_id);
+        results.push(failCheck('canvas', name, faultMessage(fault), remediation));
+    }
+    return results;
+}
+async function runChecksForScope(scope, opts) {
+    const results = [];
+    const root = scopeRoot(scope);
+    if (!root)
+        return results;
+    const cfg = readConfig(scope);
+    // Check: every config marketplace entry has a corresponding directory
+    const mktDir = marketplacesDir(scope);
+    for (const name of Object.keys(cfg.marketplaces)) {
+        if (!mktDir) {
+            results.push(failCheck(scope, `marketplace:${name}:dir`, `marketplaces directory unavailable`));
+            continue;
+        }
+        const dir = join(mktDir, name);
+        if (!pathExists(dir)) {
+            const remediation = {
+                kind: 'remove_config_key',
+                description: `Drop stale config entry config.${scope}.marketplaces.${name}`,
+                scope,
+                configKey: `marketplaces.${name}`,
+            };
+            if (opts.fix && await applyRemediation(remediation)) {
+                results.push({ scope, name: `marketplace:${name}:dir`, status: 'fail', message: `directory missing — removed stale config entry`, fixed: true, remediation });
+            }
+            else {
+                results.push(failCheck(scope, `marketplace:${name}:dir`, `directory missing: ${dir}`, remediation));
+            }
+        }
+        else {
+            results.push(pass(scope, `marketplace:${name}:dir`, `directory exists`));
+        }
+    }
+    // Check: every config plugin entry has a corresponding directory
+    const plugDir = pluginsDir(scope);
+    for (const name of Object.keys(cfg.plugins)) {
+        if (!plugDir) {
+            results.push(failCheck(scope, `plugin:${name}:dir`, `plugins directory unavailable`));
+            continue;
+        }
+        const dir = join(plugDir, name);
+        if (!pathExists(dir)) {
+            const remediation = {
+                kind: 'remove_config_key',
+                description: `Drop stale config entry config.${scope}.plugins.${name}`,
+                scope,
+                configKey: `plugins.${name}`,
+            };
+            if (opts.fix && await applyRemediation(remediation)) {
+                results.push({ scope, name: `plugin:${name}:dir`, status: 'fail', message: `directory missing — removed stale config entry`, fixed: true, remediation });
+            }
+            else {
+                results.push(failCheck(scope, `plugin:${name}:dir`, `directory missing: ${dir}`, remediation));
+            }
+        }
+        else {
+            results.push(pass(scope, `plugin:${name}:dir`, `directory exists`));
+        }
+    }
+    // Check: every marketplace directory has a valid manifest
+    if (mktDir && pathExists(mktDir)) {
+        for (const name of listDirs(mktDir)) {
+            const dir = join(mktDir, name);
+            const manifest = readMarketplaceManifest(dir);
+            if (!manifest) {
+                const remediation = {
+                    kind: 'rm_path',
+                    description: `Remove dangling marketplace directory (no valid .crouter-marketplace/marketplace.json)`,
+                    path: dir,
+                };
+                if (opts.fix && await applyRemediation(remediation)) {
+                    results.push({ scope, name: `marketplace:${name}:manifest`, status: 'fail', message: `no valid marketplace.json — removed dangling directory`, fixed: true, remediation });
+                }
+                else {
+                    results.push(failCheck(scope, `marketplace:${name}:manifest`, `no valid marketplace.json in ${dir}`, remediation));
+                }
+            }
+            else {
+                results.push(pass(scope, `marketplace:${name}:manifest`, `manifest valid`));
+                // Check: marketplace plugins[].source paths resolve (relative paths only)
+                for (const entry of manifest.plugins) {
+                    if (entry.source.startsWith('http://') || entry.source.startsWith('https://') || entry.source.startsWith('git@')) {
+                        continue;
+                    }
+                    const resolved = join(dir, entry.source);
+                    if (!pathExists(resolved)) {
+                        results.push(failCheck(scope, `marketplace:${name}:plugin-source:${entry.name}`, `source path does not resolve: ${resolved}`));
+                    }
+                    else {
+                        results.push(pass(scope, `marketplace:${name}:plugin-source:${entry.name}`, `source resolves`));
+                    }
+                }
+            }
+        }
+    }
+    // Check: every plugin directory has a valid manifest + no duplicate names
+    const seenPluginNames = new Map();
+    if (plugDir && pathExists(plugDir)) {
+        for (const name of listDirs(plugDir)) {
+            const dir = join(plugDir, name);
+            const manifest = readPluginManifest(dir);
+            if (!manifest) {
+                const remediation = {
+                    kind: 'rm_path',
+                    description: `Remove dangling plugin directory (no valid .crouter-plugin/plugin.json)`,
+                    path: dir,
+                };
+                if (opts.fix && await applyRemediation(remediation)) {
+                    results.push({ scope, name: `plugin:${name}:manifest`, status: 'fail', message: `no valid plugin.json — removed dangling directory`, fixed: true, remediation });
+                }
+                else {
+                    results.push(failCheck(scope, `plugin:${name}:manifest`, `no valid plugin.json in ${dir}`, remediation));
+                }
+                continue;
+            }
+            results.push(pass(scope, `plugin:${name}:manifest`, `manifest valid`));
+            // Duplicate names
+            if (seenPluginNames.has(name)) {
+                results.push(failCheck(scope, `plugin:${name}:duplicate`, `duplicate plugin name within scope (also at ${seenPluginNames.get(name)})`));
+            }
+            else {
+                seenPluginNames.set(name, dir);
+            }
+            // Git remote check (slow, opt-in)
+            if (opts.remote && manifest.source) {
+                const res = lsRemote(manifest.source);
+                if (res.status !== 0) {
+                    results.push(failCheck(scope, `plugin:${name}:remote`, `git remote unreachable: ${manifest.source}`));
+                }
+                else {
+                    results.push(pass(scope, `plugin:${name}:remote`, `git remote reachable`));
+                }
+            }
+        }
+    }
+    return results;
+}
+export const sysDoctorLeaf = defineLeaf({
+    name: 'doctor',
+    description: 'diagnose installation health',
+    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, a config entry points at a directory that no longer exists, or a plugin command/hook declaration is malformed. Reports each problem with a structured remediation, and can apply the safe repairs for you.',
+    help: {
+        name: 'sys doctor',
+        summary: 'diagnose runtime integrity, missing manifests, and broken config entries',
+        params: [
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to check. Default: all scopes.' },
+            { kind: 'flag', name: 'fix', type: 'bool', required: false, constraint: 'Apply each non-pass check\'s remediation and report what was fixed.' },
+            { kind: 'flag', name: 'remote', type: 'bool', required: false, constraint: 'Check git remotes with ls-remote (slow — makes network calls).' },
+        ],
+        output: [
+            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. bin:<name> checks report bare-binary contributions (a `bin` block in a plugin manifest or a scope config.json): a pass names the contributor and the resolved target, a fail names an unsafe/reserved command name, malformed target declaration, missing/non-executable/escaping target, or same-precedence name collision that installed nothing; their remediation is always a human_action. humanActions:<name>@<config-origin> checks validate each user/project scope completion-action declaration: action-name and argv shape, cwd directory, argv[0] regular-file existence, and execute permission; they never execute an action. A malformed effective declaration fails; a malformed shadowed declaration is a pass-level warning that names the winning and shadowed origins. requires:<name> checks report each enabled plugin manifest PATH requirement: a pass names the plugin and resolved executable path; a fail names the plugin and carries its declared install hint as remediation. Runtime checks validate selected and process generation manifests, sealing/containment, and full SHA-256 inventories. terminal:nerd-font (user scope) reports whether a Nerd Font is installed for the viewer\'s icon glyphs; its remediation is always a human_action carrying the platform install command, never auto-fixed. Plugin checks appear as plugin:<name>:commands and plugin:<name>:hooks; both are validated statically and never execute plugin code. Hook failures identify manifest/path/target/event/collision problems and carry disable/update/remove/show remediation; healthy command hooks list effective target, phase, and op, while lifecycle hooks list event, phase, op, and effects. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action; fault human_action remediations include the canonical logs command. Sorted by scope then name.' },
+            { name: 'ok', type: 'boolean', required: true, constraint: 'True when no unresolved fail checks remain.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Read-only unless --fix is passed. Runtime verification reads and hashes every selected/process generation file; plugin command and hook manifests, bare-binary (`bin`) declarations, humanActions declarations, and advisory `requires` PATH checks never execute plugin or contributed binaries.',
+            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings and plugin command/hook findings stay read-only (--fix never chmods or rewrites third-party plugin content).',
+            'Each non-pass result carries a structured `remediation` describing the fix action (absolute paths, exact config keys, or a human_action with its command) so callers can apply it directly without --fix.',
+        ],
+    },
+    run: async (input) => {
+        const scopeArg = input['scope'];
+        const fix = input['fix'];
+        const remote = input['remote'];
+        const scopes = listScopes(scopeArg);
+        const allResults = [];
+        for (const scope of scopes) {
+            const results = await runChecksForScope(scope, { fix, remote });
+            allResults.push(...results);
+        }
+        if (scopes.includes('user'))
+            allResults.push(runNerdFontCheck());
+        allResults.push(...await runCommandPluginChecks(scopes));
+        allResults.push(...await runHookPluginChecks(scopes));
+        allResults.push(...runBinContributionChecks(scopes));
+        allResults.push(...runHumanActionChecks(scopes));
+        allResults.push(...await runRequiresChecks(scopes));
+        allResults.push(...await runFaultChecks());
+        const processLocation = processGeneration();
+        allResults.push(...await generationChecks('selected', selectedGeneration(), processLocation === null));
+        allResults.push(...await generationChecks('process', processLocatedGeneration(), true));
+        // Sort by scope then name (mirrors old printResults grouping)
+        const scopeOrder = { user: 0, project: 1, builtin: 2, canvas: 3 };
+        allResults.sort((a, b) => {
+            if (a.scope !== b.scope)
+                return scopeOrder[a.scope] - scopeOrder[b.scope];
+            return a.name.localeCompare(b.name);
+        });
+        const ok = !allResults.some((r) => r.status === 'fail' && r.fixed !== true);
+        // failed count = unresolved fails
+        const failed = allResults.filter((r) => r.status === 'fail' && r.fixed !== true).length;
+        // The skeleton schema declared `ok` not `failed`; returning both for completeness
+        return { checks: allResults, ok, failed };
+    },
+});