@principles/pd-cli 1.133.0 → 1.134.0

package/dist/commands/errors-list.js

@@ -0,0 +1,368 @@
+/**
+ * pd errors list — List PD pipeline errors (failed tasks + worker errors).
+ *
+ * Usage:
+ *   pd errors list [--json] [--kind <runnerKind>] [--since <hours>] [--limit <n>] [--workspace <path>]
+ *
+ * Aggregates two error sources into a single operator-facing read-only view:
+ *   1. SQLite state.db tasks where status IN ('failed', 'needs_human_review')
+ *      (via SqliteTaskStore.listFailedTasks — Task 8).
+ *   2. worker-status.json `errors` array written by EvolutionWorker
+ *      (Task 2 extended the entry shape to { at, kind, principleId, error } | string).
+ *
+ * CLI gate compliance:
+ *   - cli-1-strict-json: --json stdout is exactly one parseable JSON object.
+ *   - cli-2-exit-stops: every process.exit(...) is immediately followed by return.
+ *   - cli-6-output-next-action: empty result includes a `nextAction` field.
+ *   - cli-4-dry-run-confirm-mutex: N/A (read-only command).
+ *
+ * Runtime contract compliance:
+ *   - rc-1-treat-as-unknown: worker-status.json parsed content is treated as unknown.
+ *   - rc-2-no-as-bypass: no `as` casts; runtime validation via typeof / Array.isArray.
+ *   - rc-4-validate-array-elements: errors array elements are validated element-wise.
+ *   - rc-5-object-hasown-not-in: Object.hasOwn used for untrusted object key checks.
+ *   - rc-9-no-silent-fallback: missing worker-status.json → workerErrors=[] with
+ *     a `workerStatusMissing` note; parse failures surface a `workerStatusWarning`.
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { SqliteConnection, SqliteTaskStore } from '@principles/core';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+/** Default and maximum values for --limit. */
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+/**
+ * Type guard: narrow `unknown` to a plain record (rc-2: no `as` bypass).
+ * Returns true only for non-null, non-array objects.
+ */
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Validate and normalize a single worker-status.json errors entry.
+ *
+ * rc-1: input is `unknown` (parsed from JSON).
+ * rc-2: no `as` — uses typeof / Object.hasOwn guards.
+ * rc-5: Object.hasOwn for key checks (not `in`).
+ *
+ * Accepts:
+ *   - string → { error: <string>, rawForm: 'string', others null }
+ *   - { at, kind, principleId, error } → normalized object
+ * Anything else → null (skipped; caller records a warning).
+ */
+function normalizeWorkerErrorEntry(entry) {
+    if (typeof entry === 'string') {
+        return {
+            at: null,
+            kind: null,
+            principleId: null,
+            error: entry,
+            rawForm: 'string',
+        };
+    }
+    // rc-2: type guard instead of `as` cast (isRecord narrows unknown → record).
+    if (!isRecord(entry)) {
+        return null;
+    }
+    // rc-5: use Object.hasOwn, not `in`, for untrusted object key checks.
+    const at = Object.hasOwn(entry, 'at') && typeof entry.at === 'string' ? entry.at : null;
+    const kind = Object.hasOwn(entry, 'kind') && typeof entry.kind === 'string' ? entry.kind : null;
+    const principleId = Object.hasOwn(entry, 'principleId') && typeof entry.principleId === 'string' ? entry.principleId : null;
+    // `error` is the only required field for the object form; if missing or
+    // non-string, fall back to JSON.stringify so we don't lose the entry.
+    let errorStr;
+    if (Object.hasOwn(entry, 'error') && typeof entry.error === 'string') {
+        errorStr = entry.error;
+    }
+    else {
+        try {
+            errorStr = JSON.stringify(entry);
+        }
+        catch {
+            errorStr = '[unserializable worker-status error entry]';
+        }
+    }
+    return {
+        at,
+        kind,
+        principleId,
+        error: errorStr,
+        rawForm: 'object',
+    };
+}
+/**
+ * Read and validate the worker-status.json `errors` array.
+ *
+ * Returns `{ entries, missing, warning }`:
+ *   - `missing: true` if the file does not exist (not an error — worker hasn't run).
+ *   - `warning: string` if the file exists but is unparseable / wrong shape
+ *     (rc-9: surface the reason, do not silently swallow).
+ *   - `entries: WorkerErrorEntry[]` validated element-wise (rc-4).
+ */
+function readWorkerStatusErrors(stateDir) {
+    const statusPath = path.join(stateDir, 'worker-status.json');
+    if (!fs.existsSync(statusPath)) {
+        return { entries: [], missing: true, warning: null };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(statusPath, 'utf8');
+    }
+    catch (err) {
+        return {
+            entries: [],
+            missing: false,
+            warning: `Failed to read worker-status.json: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // rc-1: parsed JSON is unknown.
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            entries: [],
+            missing: false,
+            warning: `Failed to parse worker-status.json: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!isRecord(parsed)) {
+        return {
+            entries: [],
+            missing: false,
+            warning: 'worker-status.json root is not a JSON object',
+        };
+    }
+    // rc-5: Object.hasOwn for untrusted key check.
+    if (!Object.hasOwn(parsed, 'errors')) {
+        // No `errors` field — treat as empty (older worker-status.json may lack it).
+        return { entries: [], missing: false, warning: null };
+    }
+    const errorsField = parsed.errors;
+    if (!Array.isArray(errorsField)) {
+        return {
+            entries: [],
+            missing: false,
+            warning: 'worker-status.json `errors` field is not an array',
+        };
+    }
+    // rc-4: validate array element types; skip malformed entries.
+    const entries = [];
+    let skipped = 0;
+    for (const item of errorsField) {
+        const normalized = normalizeWorkerErrorEntry(item);
+        if (normalized === null) {
+            skipped++;
+            continue;
+        }
+        entries.push(normalized);
+    }
+    const warning = skipped > 0
+        ? `Skipped ${skipped} malformed worker-status.json error entr${skipped === 1 ? 'y' : 'ies'}`
+        : null;
+    return { entries, missing: false, warning };
+}
+function formatTextOutput(result, workspaceDir) {
+    const lines = [];
+    lines.push('PD Errors List');
+    lines.push(`  workspace:   ${workspaceDir}`);
+    lines.push(`  total:       ${result.total}  (tasks: ${result.tasks.length}, workerErrors: ${result.workerErrors.length})`);
+    lines.push('');
+    if (result.workerStatusMissing) {
+        lines.push(`  workerStatus: (missing — ${result.workerStatusPath} not found)`);
+    }
+    else if (result.workerStatusWarning) {
+        lines.push(`  workerStatus: WARNING — ${result.workerStatusWarning}`);
+    }
+    if (result.tasks.length > 0) {
+        lines.push('');
+        lines.push('Failed tasks:');
+        for (const t of result.tasks) {
+            // rc-2: type guard instead of `as` cast — tasks come from SqliteTaskStore
+            // which returns FailedTaskSummary[], but we typed tasks as unknown[] to
+            // keep the result interface decoupled from core's type exports.
+            const task = isRecord(t) ? t : null;
+            const taskId = task && typeof task.taskId === 'string' ? task.taskId : '?';
+            const taskKind = task && typeof task.taskKind === 'string' ? task.taskKind : '?';
+            const status = task && typeof task.status === 'string' ? task.status : '?';
+            const lastError = task && typeof task.lastError === 'string' ? task.lastError : '-';
+            const attemptCount = task && typeof task.attemptCount === 'number' ? task.attemptCount : 0;
+            const painId = task && typeof task.painId === 'string' ? task.painId : '-';
+            const lastAttemptAt = task && typeof task.lastAttemptAt === 'string' ? task.lastAttemptAt : '-';
+            lines.push(`  - ${taskId} (${taskKind}) [${status}]`);
+            lines.push(`    painId:        ${painId}`);
+            lines.push(`    lastError:     ${lastError}`);
+            lines.push(`    attemptCount:  ${attemptCount}`);
+            lines.push(`    lastAttemptAt: ${lastAttemptAt}`);
+        }
+    }
+    if (result.workerErrors.length > 0) {
+        lines.push('');
+        lines.push('Worker errors:');
+        for (const e of result.workerErrors) {
+            const at = e.at ?? '-';
+            const kind = e.kind ?? '-';
+            const pid = e.principleId ?? '-';
+            lines.push(`  - [${at}] kind=${kind} principleId=${pid}`);
+            lines.push(`    error: ${e.error}`);
+        }
+    }
+    if (result.total === 0) {
+        lines.push('');
+        lines.push('No errors found. PD pipeline is healthy.');
+    }
+    return lines.join('\n');
+}
+export async function handleErrorsList(opts) {
+    const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+    const stateDir = path.join(workspaceDir, '.pd');
+    const stateDbPath = path.join(stateDir, 'state.db');
+    // Pre-check: if state.db does not exist, fail loud (cli-2-exit-stops + rc-9).
+    if (!fs.existsSync(stateDbPath)) {
+        const msg = `Error: state.db not found at ${stateDbPath}. Workspace may not be initialized.`;
+        if (opts.json) {
+            // cli-1: even error JSON is a single object on stdout? No — cli-2 says
+            // failure paths write to stderr. JSON error envelope goes to stderr too
+            // so stdout stays clean (cli-1-strict-json guarantees stdout is parseable).
+            process.stderr.write(JSON.stringify({
+                ok: false,
+                reason: msg,
+                nextAction: 'Run "pd runtime init --confirm --workspace <dir>" to initialize databases, then retry.',
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stderr.write(msg + '\n');
+        }
+        process.exitCode = 1;
+        return; // cli-2-exit-stops
+    }
+    // Resolve and validate --limit.
+    let limit = DEFAULT_LIMIT;
+    if (opts.limit !== undefined) {
+        if (!Number.isFinite(opts.limit) || opts.limit <= 0) {
+            const msg = `Error: --limit must be a positive integer, got ${opts.limit}`;
+            // cli-6-output-next-action: mirror the state.db missing branch — when
+            // opts.json is true, emit a structured { ok:false, reason, nextAction }
+            // envelope to stderr instead of plain text.
+            if (opts.json) {
+                process.stderr.write(JSON.stringify({
+                    ok: false,
+                    reason: msg,
+                    nextAction: 'Pass --limit as a positive integer (e.g. --limit 50). Maximum is 500.',
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(msg + '\n');
+            }
+            process.exitCode = 1;
+            return; // cli-2-exit-stops
+        }
+        limit = Math.min(opts.limit, MAX_LIMIT);
+    }
+    // Resolve --since (hours → Unix-ms timestamp).
+    let sinceMs;
+    if (opts.since !== undefined) {
+        if (!Number.isFinite(opts.since) || opts.since < 0) {
+            const msg = `Error: --since must be a non-negative number of hours, got ${opts.since}`;
+            // cli-6-output-next-action: same JSON envelope pattern as --limit above.
+            if (opts.json) {
+                process.stderr.write(JSON.stringify({
+                    ok: false,
+                    reason: msg,
+                    nextAction: 'Pass --since as a non-negative number of hours (e.g. --since 24 for the last 24h).',
+                }, null, 2) + '\n');
+            }
+            else {
+                process.stderr.write(msg + '\n');
+            }
+            process.exitCode = 1;
+            return; // cli-2-exit-stops
+        }
+        sinceMs = Date.now() - opts.since * 3600 * 1000;
+    }
+    const connection = new SqliteConnection({ workspaceDir, readonly: true });
+    try {
+        const taskStore = new SqliteTaskStore(connection);
+        const tasks = await taskStore.listFailedTasks({
+            kind: opts.kind,
+            since: sinceMs,
+            limit,
+        });
+        const { entries: workerErrors, missing, warning } = readWorkerStatusErrors(stateDir);
+        const total = tasks.length + workerErrors.length;
+        const result = {
+            tasks,
+            workerErrors,
+            total,
+            workerStatusPath: path.join(stateDir, 'worker-status.json'),
+        };
+        if (missing) {
+            result.workerStatusMissing = true;
+        }
+        if (warning) {
+            result.workerStatusWarning = warning;
+        }
+        // cli-6-output-next-action: include nextAction only when there are no errors.
+        if (total === 0) {
+            result.nextAction = 'No errors found. PD pipeline is healthy.';
+        }
+        if (opts.json) {
+            // cli-1-strict-json: stdout is exactly one parseable JSON object.
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(formatTextOutput(result, workspaceDir));
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (opts.json) {
+            process.stderr.write(JSON.stringify({
+                ok: false,
+                reason: `Failed to list errors: ${message}`,
+                nextAction: 'Check workspace path and state.db readability, then retry.',
+            }, null, 2) + '\n');
+        }
+        else {
+            process.stderr.write(`Error: ${message}\n`);
+        }
+        process.exitCode = 1;
+        return; // cli-2-exit-stops
+    }
+    finally {
+        connection.close();
+    }
+}
+/**
+ * Register the `errors` command group with `list` subcommand on a Commander
+ * program. Used by both production CLI (src/index.ts) and parser-level tests
+ * (cli-7-test-wiring).
+ *
+ * The `errors` command group is hidden from `pd --help` (operator diagnostic,
+ * same convention as `legacy` / `artifact` / `runtime recovery`).
+ */
+export function registerErrorsListCommand(program) {
+    const errorsCmd = program
+        .command('errors', { hidden: true })
+        .description('PD pipeline error inspection (failed tasks + worker errors)');
+    errorsCmd
+        .command('list')
+        .description('List PD pipeline errors — failed tasks + worker-status.json errors')
+        .option('-w, --workspace <path>', 'Workspace directory')
+        .option('--json', 'Output raw JSON (cli-1-strict-json: stdout is exactly one JSON object)')
+        .option('--kind <runnerKind>', 'Filter failed tasks by task_kind (e.g. diagnostician, dreamer)')
+        .option('--since <hours>', 'Only show errors from the last N hours (non-negative number)', parseInt)
+        .option('--limit <n>', 'Max failed tasks to return (default: 50, max: 200)', parseInt)
+        .action(async (opts) => {
+        await handleErrorsList({
+            workspace: opts.workspace,
+            json: opts.json === true,
+            kind: opts.kind,
+            since: opts.since,
+            limit: opts.limit,
+        });
+    });
+    return errorsCmd;
+}
+//# sourceMappingURL=errors-list.js.map

package/dist/commands/errors-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-list.js","sourceRoot":"","sources":["../../src/commands/errors-list.ts"],"names":[],"mappings":"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"}

package/dist/commands/health-codex.d.ts

@@ -0,0 +1,7 @@
+interface CodexHealthOptions {
+    workspace?: string;
+    json?: boolean;
+}
+export declare function handleHealthCodex(opts?: CodexHealthOptions): Promise<void>;
+export {};
+//# sourceMappingURL=health-codex.d.ts.map

package/dist/commands/health-codex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-codex.d.ts","sourceRoot":"","sources":["../../src/commands/health-codex.ts"],"names":[],"mappings":"AAsBA,UAAU,kBAAkB;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AA2GD,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoHpF"}

package/dist/commands/health-codex.js

@@ -0,0 +1,209 @@
+/**
+ * pd health --host codex command implementation.
+ *
+ * Reports Codex adapter/runtime versions, host.codex feature flag state,
+ * hook trust status, and dual global/plugin hook registration detection.
+ *
+ * CLI gate compliance:
+ * - cli-1: --json outputs exactly one parseable JSON object on stdout.
+ * - cli-2: exit paths stop execution (return after process.exit).
+ * - cli-5: failure paths do not mutate state (read-only throughout).
+ * - cli-6: every degraded/refused result includes reason + nextAction.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { createRequire } from 'module';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { loadPdConfigForPlugin, resolveNearestPdWorkspace } from '@principles/host-runtime';
+import { computeFeatureFlagsFromConfig, isFeatureEnabled } from '@principles/core/runtime-v2';
+const require = createRequire(import.meta.url);
+function readPackageVersion(packageName) {
+    try {
+        const pkgJsonPath = require.resolve(`${packageName}/package.json`);
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+        if (typeof pkg.version === 'string')
+            return pkg.version;
+        return 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function detectCodexConfigDir() {
+    const home = os.homedir();
+    const codexDir = path.join(home, '.codex');
+    if (fs.existsSync(codexDir))
+        return codexDir;
+    return undefined;
+}
+function detectHooksTrust(codexConfigDir) {
+    if (!codexConfigDir) {
+        return {
+            detectable: false,
+            reason: 'codex_config_dir_not_found',
+            nextAction: 'Install Codex CLI (>= 0.147) and run `codex` once to create ~/.codex/, then re-run `pd health --host codex` to verify hook trust state.',
+        };
+    }
+    // Codex stores hook trust in config.toml under [features] hooks = true|false.
+    // We do a best-effort text scan rather than a full TOML parse to avoid a new
+    // dependency. If the file is missing or the hook line is absent, we report
+    // undetectable with a clear next action.
+    const configTomlPath = path.join(codexConfigDir, 'config.toml');
+    if (!fs.existsSync(configTomlPath)) {
+        return {
+            detectable: false,
+            reason: 'config_toml_not_found',
+            nextAction: `Open Codex and run /hooks to trust PD hooks, then re-run \`pd health --host codex\`. Expected config at ${configTomlPath}.`,
+        };
+    }
+    try {
+        const raw = fs.readFileSync(configTomlPath, 'utf8');
+        const match = /hooks\s*=\s*(true|false)/i.exec(raw);
+        if (!match || !match[1]) {
+            return {
+                detectable: false,
+                reason: 'hooks_setting_not_found_in_config',
+                nextAction: 'Open Codex and run /hooks to trust PD hooks. Codex config.toml exists but has no `hooks` setting under [features].',
+            };
+        }
+        return { detectable: true, trusted: match[1].toLowerCase() === 'true' };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            detectable: false,
+            reason: `config_toml_read_failed: ${message.slice(0, 200)}`,
+            nextAction: `Check read permissions on ${configTomlPath} and re-run \`pd health --host codex\`.`,
+        };
+    }
+}
+function detectDualRegistration(codexConfigDir) {
+    const globalHooksPath = codexConfigDir ? path.join(codexConfigDir, 'hooks.json') : undefined;
+    // Plugin hooks are declared in a plugin manifest; we cannot reliably detect
+    // them from outside Codex. We only flag the global-hooks path and let the
+    // operator confirm plugin registration via /hooks in Codex.
+    const globalHooksExists = globalHooksPath ? fs.existsSync(globalHooksPath) : false;
+    if (globalHooksExists) {
+        return {
+            detected: true,
+            globalHooksPath,
+            reason: 'global_hooks_json_present',
+            nextAction: 'Global ~/.codex/hooks.json is installed. If the PD Codex plugin is also installed via marketplace, this may cause double-registration. Choose ONE: keep global hooks.json (fallback path) OR uninstall it and use the plugin (recommended). To remove global PD entries, run `create-principles-disciple uninstall --host codex`.',
+        };
+    }
+    return { detected: false };
+}
+export async function handleHealthCodex(opts = {}) {
+    const generatedAt = new Date().toISOString();
+    const workspaceDir = opts.workspace
+        ? path.resolve(opts.workspace)
+        : resolveWorkspaceDir();
+    const warnings = [];
+    // Resolve workspace via the shared host-runtime resolver so pd-cli reports
+    // the same workspace the Codex hook would resolve.
+    const resolution = resolveNearestPdWorkspace(workspaceDir);
+    let resolvedWorkspace;
+    let featureFlagSource;
+    let hostCodexEnabled = false;
+    if (!resolution.ok) {
+        resolvedWorkspace = workspaceDir;
+        featureFlagSource = 'defaults';
+        warnings.push(`workspace_not_resolved: ${resolution.reason} — ${resolution.nextAction}`);
+    }
+    else {
+        resolvedWorkspace = resolution.workspaceDir;
+        const configLoad = loadPdConfigForPlugin(resolvedWorkspace);
+        featureFlagSource = configLoad.source;
+        const flags = computeFeatureFlagsFromConfig(configLoad.effective);
+        hostCodexEnabled = isFeatureEnabled(flags, 'host.codex');
+        if (!configLoad.ok) {
+            for (const error of configLoad.errors) {
+                warnings.push(`config_error: ${error.reason} — ${error.nextAction}`);
+            }
+        }
+    }
+    const adapterVersion = readPackageVersion('@principles/codex-adapter');
+    const runtimeVersion = readPackageVersion('@principles/host-runtime');
+    const codexConfigDir = detectCodexConfigDir();
+    const hooksTrust = detectHooksTrust(codexConfigDir);
+    const dualRegistration = detectDualRegistration(codexConfigDir);
+    if (hooksTrust.reason)
+        warnings.push(`hooks_trust: ${hooksTrust.reason}`);
+    if (dualRegistration.reason)
+        warnings.push(`dual_registration: ${dualRegistration.reason}`);
+    const report = {
+        generatedAt,
+        host: 'codex',
+        workspace: resolvedWorkspace,
+        adapterVersion,
+        runtimeVersion,
+        featureFlag: {
+            name: 'host.codex',
+            enabled: hostCodexEnabled,
+            source: featureFlagSource,
+            ...(hostCodexEnabled
+                ? {}
+                : {
+                    reason: 'host_codex_disabled',
+                    nextAction: `Enable the Codex host adapter by setting features.host.codex.enabled=true in ${resolvedWorkspace}/.pd/config.yaml, then re-run \`pd health --host codex\`.`,
+                }),
+        },
+        hooksTrust,
+        dualRegistration,
+        warnings,
+    };
+    if (opts.json) {
+        // cli-1: exactly one parseable JSON object on stdout.
+        console.log(JSON.stringify(report, null, 2));
+        // cli-2: exit-stops. Non-zero only when host.codex is disabled AND hooks
+        // are not trusted — the operator must act before Codex activation works.
+        if (!hostCodexEnabled && !hooksTrust.trusted) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // Text output — still includes explicit nextAction per cli-6.
+    console.log(`generatedAt: ${report.generatedAt}`);
+    console.log(`host: ${report.host}`);
+    console.log(`workspace: ${report.workspace}`);
+    console.log(`adapterVersion: ${report.adapterVersion}`);
+    console.log(`runtimeVersion: ${report.runtimeVersion}`);
+    console.log(`featureFlag.name: ${report.featureFlag.name}`);
+    console.log(`featureFlag.enabled: ${report.featureFlag.enabled}`);
+    console.log(`featureFlag.source: ${report.featureFlag.source}`);
+    if (report.featureFlag.reason) {
+        console.log(`featureFlag.reason: ${report.featureFlag.reason}`);
+        console.log(`featureFlag.nextAction: ${report.featureFlag.nextAction ?? ''}`);
+    }
+    console.log(`hooksTrust.detectable: ${report.hooksTrust.detectable}`);
+    if (report.hooksTrust.trusted !== undefined) {
+        console.log(`hooksTrust.trusted: ${report.hooksTrust.trusted}`);
+    }
+    if (report.hooksTrust.reason) {
+        console.log(`hooksTrust.reason: ${report.hooksTrust.reason}`);
+        console.log(`hooksTrust.nextAction: ${report.hooksTrust.nextAction ?? ''}`);
+    }
+    console.log(`dualRegistration.detected: ${report.dualRegistration.detected}`);
+    if (report.dualRegistration.globalHooksPath) {
+        console.log(`dualRegistration.globalHooksPath: ${report.dualRegistration.globalHooksPath}`);
+    }
+    if (report.dualRegistration.reason) {
+        console.log(`dualRegistration.reason: ${report.dualRegistration.reason}`);
+        console.log(`dualRegistration.nextAction: ${report.dualRegistration.nextAction ?? ''}`);
+    }
+    if (report.warnings.length > 0) {
+        console.log(`warnings:`);
+        for (const w of report.warnings)
+            console.log(`  - ${w}`);
+    }
+    console.log('');
+    if (!hostCodexEnabled) {
+        console.warn(`⚠️  host.codex feature flag is disabled. Enable it in ${resolvedWorkspace}/.pd/config.yaml under features.host.codex.enabled to activate Codex hooks.`);
+    }
+    if (!hooksTrust.trusted && !hooksTrust.detectable) {
+        console.warn(`⚠️  Hook trust state could not be detected. ${hooksTrust.nextAction ?? ''}`);
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=health-codex.js.map

package/dist/commands/health-codex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-codex.js","sourceRoot":"","sources":["../../src/commands/health-codex.ts"],"names":[],"mappings":"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"}

package/dist/commands/health.d.ts

@@ -7,10 +7,34 @@
  * to provide Runtime V2 health diagnostics.
  * Uses read models from @principles/core/runtime-v2 (no direct ledger access).
  */
+import type { Command } from 'commander';
+import { handleHealthCodex } from './health-codex.js';
 interface HealthOptions {
     workspace?: string;
     json?: boolean;
 }
 export declare function handleHealth(opts?: HealthOptions): Promise<void>;
+/**
+ * Handlers backing the `pd health` command. Injected so the registration
+ * wiring test can exercise the real `registerHealthCommand` without executing
+ * real workspace/DB I/O; production uses the defaults.
+ */
+interface HealthCommandHandlers {
+    health?: typeof handleHealth;
+    healthCodex?: typeof handleHealthCodex;
+}
+/**
+ * Registers the `pd health` command on a Commander program.
+ *
+ * cli-7 test-wiring: this is the single registration used by both the CLI
+ * entrypoint and the wiring test, so a test exercising it covers the real
+ * production command (options + --host dispatch), not a copy.
+ *
+ * --host accepts only `openclaw` and `codex`; any other value is rejected with
+ * a structured reason/nextAction and a non-zero exit (cli-1/cli-2/cli-6). When
+ * `--json` is set, the rejection is emitted as exactly one parseable JSON
+ * object on stdout.
+ */
+export declare function registerHealthCommand(program: Command, handlers?: HealthCommandHandlers): void;
 export {};
 //# sourceMappingURL=health.d.ts.map

package/dist/commands/health.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/commands/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkCH,UAAU,aAAa;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAoBD,wBAAsB,YAAY,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4H1E"}
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/commands/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AA0BtD,UAAU,aAAa;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAoBD,wBAAsB,YAAY,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4H1E;AAED;;;;GAIG;AACH,UAAU,qBAAqB;IAC7B,MAAM,CAAC,EAAE,OAAO,YAAY,CAAC;IAC7B,WAAW,CAAC,EAAE,OAAO,iBAAiB,CAAC;CACxC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAE,qBAA0B,GAAG,IAAI,CAkClG"}