@kbediako/codex-orchestrator 0.1.0

package/dist/orchestrator/src/cli/pipelines/hiFiDesignToolkit.js

@@ -0,0 +1,71 @@
+const DESIGN_TOOLKIT_ENV = {
+    DESIGN_PIPELINE: '1',
+    DESIGN_TOOLKIT: '1'
+};
+export const hiFiDesignToolkitPipeline = {
+    id: 'hi-fi-design-toolkit',
+    title: 'Hi-Fi Design Toolkit',
+    description: 'Runs the hi-fi design toolkit pipeline to extract, tokenize, self-correct, and publish design artifacts.',
+    tags: ['design', 'hi-fi'],
+    stages: [
+        {
+            kind: 'command',
+            id: 'design-config',
+            title: 'Resolve design configuration',
+            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/prepare.js"',
+            env: { ...DESIGN_TOOLKIT_ENV }
+        },
+        {
+            kind: 'command',
+            id: 'design-toolkit-extract',
+            title: 'Wrap external toolkit extractor',
+            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/extract.js"',
+            env: { ...DESIGN_TOOLKIT_ENV }
+        },
+        {
+            kind: 'command',
+            id: 'design-toolkit-tokens',
+            title: 'Generate tokens and style guides',
+            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/tokens.js"',
+            env: { ...DESIGN_TOOLKIT_ENV }
+        },
+        {
+            kind: 'command',
+            id: 'design-toolkit-reference',
+            title: 'Build reference pages + self-correction',
+            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/reference.js"',
+            env: { ...DESIGN_TOOLKIT_ENV }
+        },
+        {
+            kind: 'command',
+            id: 'design-advanced-assets',
+            title: 'Generate advanced design assets',
+            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/advanced-assets.js"',
+            env: { ...DESIGN_TOOLKIT_ENV },
+            allowFailure: true,
+            summaryHint: 'Optional motion capture via Framer Motion + FFmpeg'
+        },
+        {
+            kind: 'command',
+            id: 'design-toolkit-publish',
+            title: 'Publish toolkit outputs to packages/design-system',
+            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/publish.js"',
+            env: { ...DESIGN_TOOLKIT_ENV }
+        },
+        {
+            kind: 'command',
+            id: 'design-spec-guard',
+            title: 'Optional spec-guard (if scripts/spec-guard.mjs exists)',
+            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/orchestrator/src/cli/utils/specGuardRunner.js" --dry-run',
+            env: { ...DESIGN_TOOLKIT_ENV },
+            summaryHint: 'Ensures HI-FI design specs are current before artifact write'
+        },
+        {
+            kind: 'command',
+            id: 'design-artifact-writer',
+            title: 'Persist design manifests',
+            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/write-artifacts.js"',
+            env: { ...DESIGN_TOOLKIT_ENV }
+        }
+    ]
+};

package/dist/orchestrator/src/cli/pipelines/index.js

@@ -0,0 +1,34 @@
+import { defaultDiagnosticsPipeline } from './defaultDiagnostics.js';
+import { designReferencePipeline } from './designReference.js';
+import { hiFiDesignToolkitPipeline } from './hiFiDesignToolkit.js';
+import { findPipeline } from '../config/userConfig.js';
+const builtinPipelines = new Map([
+    [defaultDiagnosticsPipeline.id, defaultDiagnosticsPipeline],
+    [designReferencePipeline.id, designReferencePipeline],
+    [hiFiDesignToolkitPipeline.id, hiFiDesignToolkitPipeline]
+]);
+function getBuiltinPipeline(id) {
+    if (!id) {
+        return null;
+    }
+    return builtinPipelines.get(id) ?? null;
+}
+export function resolvePipeline(env, options) {
+    const { pipelineId, config } = options;
+    if (pipelineId) {
+        const fromUser = findPipeline(config, pipelineId);
+        if (fromUser) {
+            return { pipeline: fromUser, source: 'user' };
+        }
+        const builtin = getBuiltinPipeline(pipelineId);
+        if (builtin) {
+            return { pipeline: builtin, source: 'default' };
+        }
+        throw new Error(`Pipeline '${pipelineId}' not found.`);
+    }
+    const defaultId = config?.defaultPipeline ?? defaultDiagnosticsPipeline.id;
+    const userPipeline = findPipeline(config, defaultId);
+    const chosen = userPipeline ?? getBuiltinPipeline(defaultId) ?? defaultDiagnosticsPipeline;
+    const source = userPipeline ? 'user' : 'default';
+    return { pipeline: chosen, source };
+}

package/dist/orchestrator/src/cli/run/environment.js

@@ -0,0 +1,24 @@
+import { join, resolve } from 'node:path';
+import { sanitizeTaskId } from '../../persistence/sanitizeTaskId.js';
+const DEFAULT_TASK_ID = '0101';
+export function resolveEnvironment() {
+    const repoRoot = resolve(process.env.CODEX_ORCHESTRATOR_ROOT ?? process.cwd());
+    const runsRoot = resolve(process.env.CODEX_ORCHESTRATOR_RUNS_DIR ?? join(repoRoot, '.runs'));
+    const outRoot = resolve(process.env.CODEX_ORCHESTRATOR_OUT_DIR ?? join(repoRoot, 'out'));
+    const rawTaskId = process.env.MCP_RUNNER_TASK_ID ?? DEFAULT_TASK_ID;
+    const taskId = normalizeTaskId(rawTaskId);
+    return { repoRoot, runsRoot, outRoot, taskId };
+}
+function normalizeTaskId(value) {
+    try {
+        return sanitizeTaskId(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (value) {
+            throw new Error(`Invalid MCP_RUNNER_TASK_ID "${value}": ${message}`);
+        }
+        throw new Error(`Invalid MCP_RUNNER_TASK_ID: ${message}`);
+    }
+}
+export { sanitizeTaskId };

package/dist/orchestrator/src/cli/run/manifest.js

@@ -0,0 +1,367 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, symlink, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { writeJsonAtomic } from '../utils/fs.js';
+import { slugify } from '../utils/strings.js';
+import { isoTimestamp } from '../utils/time.js';
+import { loadInstructionSet } from '../../../../packages/orchestrator/src/instructions/loader.js';
+import { resolveRunPaths, relativeToRepo } from './runPaths.js';
+import { ExperienceStore } from '../../persistence/ExperienceStore.js';
+import { formatExperienceInjections } from '../exec/experience.js';
+const HEARTBEAT_INTERVAL_SECONDS = 5;
+const HEARTBEAT_STALE_AFTER_SECONDS = 30;
+const MAX_ERROR_DETAIL_CHARS = 8 * 1024;
+export async function bootstrapManifest(runId, options) {
+    const { env, pipeline, parentRunId = null, taskSlug, approvalPolicy = null } = options;
+    const paths = resolveRunPaths(env, runId);
+    await mkdir(paths.runDir, { recursive: true });
+    await mkdir(paths.commandsDir, { recursive: true });
+    await mkdir(paths.errorsDir, { recursive: true });
+    const now = isoTimestamp();
+    const resumeToken = randomBytes(32).toString('hex');
+    const commands = buildCommandEntries(pipeline);
+    const manifest = {
+        version: 1,
+        task_id: env.taskId,
+        task_slug: taskSlug ?? null,
+        run_id: runId,
+        parent_run_id: parentRunId ?? null,
+        pipeline_id: pipeline.id,
+        pipeline_title: pipeline.title,
+        runner: 'codex-cli',
+        approval_policy: approvalPolicy,
+        status: 'queued',
+        status_detail: null,
+        started_at: now,
+        completed_at: null,
+        updated_at: now,
+        heartbeat_at: now,
+        heartbeat_interval_seconds: HEARTBEAT_INTERVAL_SECONDS,
+        heartbeat_stale_after_seconds: HEARTBEAT_STALE_AFTER_SECONDS,
+        artifact_root: relativeToRepo(env, paths.runDir),
+        compat_path: relative(env.repoRoot, dirname(paths.compatManifestPath)),
+        log_path: relativeToRepo(env, paths.logPath),
+        summary: null,
+        metrics_recorded: false,
+        resume_token: resumeToken,
+        resume_events: [],
+        approvals: [],
+        commands,
+        child_runs: [],
+        run_summary_path: null,
+        plan_target_id: options.planTargetId ?? null,
+        instructions_hash: null,
+        instructions_sources: [],
+        prompt_packs: [],
+        guardrails_required: pipeline.guardrailsRequired !== false,
+        learning: {
+            validation: {
+                mode: 'per-task',
+                grouping: null,
+                status: 'pending'
+            },
+            alerts: [],
+            approvals: []
+        },
+        tfgrpo: null
+    };
+    const instructions = await loadInstructionSet(env.repoRoot);
+    const experienceStore = new ExperienceStore({
+        outDir: env.outRoot,
+        runsDir: env.runsRoot,
+        maxSummaryWords: instructions.experienceMaxWords
+    });
+    const experienceSnippets = await Promise.all(instructions.promptPacks.map(async (pack) => {
+        if (!pack.experienceSlots) {
+            return [];
+        }
+        const records = await experienceStore.fetchTop({
+            domain: pack.domain,
+            limit: pack.experienceSlots,
+            taskId: env.taskId
+        });
+        return formatExperienceInjections(records, pack.experienceSlots);
+    }));
+    manifest.instructions_hash = instructions.hash || null;
+    manifest.instructions_sources = instructions.sources.map((source) => source.path);
+    manifest.prompt_packs = instructions.promptPacks.map((pack, index) => {
+        const experiences = experienceSnippets[index] ?? [];
+        return {
+            id: pack.id,
+            domain: pack.domain,
+            stamp: pack.stamp,
+            experience_slots: pack.experienceSlots,
+            sources: pack.sources.map((source) => source.path),
+            ...(experiences.length > 0 ? { experiences } : {})
+        };
+    });
+    await writeJsonAtomic(paths.manifestPath, manifest);
+    await writeFile(paths.resumeTokenPath, `${resumeToken}\n`, 'utf8');
+    await writeFile(paths.heartbeatPath, `${now}\n`, 'utf8');
+    await createCompatibilityPointer(env, paths);
+    return { manifest, paths };
+}
+export async function saveManifest(paths, manifest) {
+    manifest.updated_at = isoTimestamp();
+    await writeJsonAtomic(paths.manifestPath, manifest);
+}
+export async function loadManifest(env, runId) {
+    const paths = resolveRunPaths(env, runId);
+    const raw = await readFile(paths.manifestPath, 'utf8');
+    const manifest = JSON.parse(raw);
+    return { manifest, paths };
+}
+export function updateCommandStatus(manifest, commandIndex, changes) {
+    const entry = manifest.commands[commandIndex];
+    if (!entry) {
+        throw new Error(`Manifest command index ${commandIndex} missing.`);
+    }
+    Object.assign(entry, changes);
+    manifest.updated_at = isoTimestamp();
+    return entry;
+}
+export async function appendCommandError(env, paths, manifest, command, reason, details) {
+    const filename = `${String(command.index).padStart(2, '0')}-${slugify(command.id)}.json`;
+    const errorPath = join(paths.errorsDir, filename);
+    const payload = {
+        run_id: manifest.run_id,
+        task_id: manifest.task_id,
+        command_index: command.index,
+        command_id: command.id,
+        command: command.command,
+        reason,
+        details: sanitizeErrorDetails(details),
+        created_at: isoTimestamp()
+    };
+    await writeJsonAtomic(errorPath, payload);
+    return relativeToRepo(env, errorPath);
+}
+function sanitizeErrorDetails(details) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(details)) {
+        if (typeof value === 'string') {
+            if (value.length > MAX_ERROR_DETAIL_CHARS) {
+                sanitized[key] = `${value.slice(0, MAX_ERROR_DETAIL_CHARS)}…`;
+                const truncatedKey = `${key}_truncated`;
+                if (!(truncatedKey in details)) {
+                    sanitized[truncatedKey] = true;
+                }
+            }
+            else {
+                sanitized[key] = value;
+            }
+        }
+        else {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+}
+export function updateHeartbeat(manifest) {
+    manifest.heartbeat_at = isoTimestamp();
+    if (manifest.status === 'in_progress') {
+        manifest.status_detail = null;
+    }
+}
+export function resetForResume(manifest) {
+    manifest.completed_at = null;
+    manifest.metrics_recorded = false;
+    manifest.status = 'in_progress';
+    manifest.status_detail = 'resuming';
+    manifest.guardrail_status = undefined;
+}
+export function recordResumeEvent(manifest, event) {
+    manifest.resume_events.push({ ...event, timestamp: isoTimestamp() });
+}
+export function ensureGuardrailStatus(manifest) {
+    if (manifest.guardrail_status) {
+        return manifest.guardrail_status;
+    }
+    const snapshot = computeGuardrailStatus(manifest);
+    manifest.guardrail_status = snapshot;
+    return snapshot;
+}
+export function buildGuardrailSummary(manifest) {
+    return ensureGuardrailStatus(manifest).summary;
+}
+export function upsertGuardrailSummary(manifest) {
+    const summary = buildGuardrailSummary(manifest);
+    const existing = manifest.summary ? manifest.summary.split('\n') : [];
+    const filtered = existing.filter((line) => !line.toLowerCase().startsWith('guardrails:'));
+    filtered.push(summary);
+    manifest.summary = filtered.join('\n').trim();
+    if (manifest.summary.length === 0) {
+        manifest.summary = summary;
+    }
+}
+function computeGuardrailStatus(manifest) {
+    const guardrailCommands = selectGuardrailCommands(manifest);
+    const guardrailsRequired = manifest.guardrails_required ?? true;
+    const counts = {
+        total: guardrailCommands.length,
+        succeeded: 0,
+        failed: 0,
+        skipped: 0,
+        other: 0
+    };
+    for (const entry of guardrailCommands) {
+        if (entry.status === 'succeeded') {
+            counts.succeeded += 1;
+        }
+        else if (entry.status === 'failed') {
+            counts.failed += 1;
+        }
+        else if (entry.status === 'skipped') {
+            counts.skipped += 1;
+        }
+        else {
+            counts.other += 1;
+        }
+    }
+    const present = counts.succeeded > 0;
+    let recommendation = null;
+    if (counts.total === 0) {
+        recommendation = guardrailsRequired
+            ? 'Guardrail command missing; run "codex-orchestrator start diagnostics --approval-policy never --format json --no-interactive" to capture reviewer diagnostics.'
+            : null;
+    }
+    else if (counts.failed > 0) {
+        recommendation =
+            'Guardrail command failed; re-run "codex-orchestrator start diagnostics --approval-policy never --format json --no-interactive" to gather failure artifacts.';
+    }
+    const summary = formatGuardrailSummary(counts);
+    return {
+        present,
+        recommendation,
+        summary,
+        computed_at: isoTimestamp(),
+        counts
+    };
+}
+function selectGuardrailCommands(manifest) {
+    return manifest.commands.filter((entry) => entry.command?.includes('spec-guard'));
+}
+function formatGuardrailSummary(counts) {
+    if (counts.total === 0) {
+        return 'Guardrails: spec-guard command not found.';
+    }
+    if (counts.failed > 0) {
+        return `Guardrails: spec-guard failed (${counts.failed}/${counts.total} failed).`;
+    }
+    if (counts.succeeded === counts.total) {
+        return `Guardrails: spec-guard succeeded (${counts.total} passed).`;
+    }
+    if (counts.skipped === counts.total) {
+        return `Guardrails: spec-guard skipped (all ${counts.total} skipped).`;
+    }
+    const parts = [];
+    if (counts.succeeded > 0) {
+        parts.push(`${counts.succeeded} passed`);
+    }
+    if (counts.skipped > 0) {
+        parts.push(`${counts.skipped} skipped`);
+    }
+    if (counts.other > 0) {
+        parts.push(`${counts.other} pending`);
+    }
+    return `Guardrails: spec-guard partial (${parts.join(', ')} of ${counts.total}).`;
+}
+export function appendSummary(manifest, message) {
+    if (!message) {
+        return;
+    }
+    if (!manifest.summary) {
+        manifest.summary = message;
+        return;
+    }
+    if (manifest.summary.includes(message)) {
+        return;
+    }
+    manifest.summary = `${manifest.summary}\n${message}`;
+}
+export function finalizeStatus(manifest, status, detail) {
+    manifest.status = status;
+    manifest.status_detail = detail ?? null;
+    manifest.completed_at = isoTimestamp();
+}
+export async function writeHeartbeatFile(paths, manifest) {
+    await writeFile(paths.heartbeatPath, `${manifest.heartbeat_at ?? isoTimestamp()}\n`, 'utf8');
+}
+async function createCompatibilityPointer(env, paths) {
+    await mkdir(paths.compatDir, { recursive: true });
+    await mkdir(paths.localCompatDir, { recursive: true });
+    const relativeManifest = relative(env.repoRoot, paths.manifestPath);
+    const artifactRootRelative = relative(env.repoRoot, paths.runDir);
+    try {
+        await writeJsonAtomic(paths.compatManifestPath, {
+            redirect_to: artifactRootRelative,
+            manifest: relativeManifest,
+            created_at: isoTimestamp(),
+            note: 'Generated by codex CLI for backward compatibility.'
+        });
+    }
+    catch (error) {
+        // Best effort; leave a stub if atomic write fails.
+        await writeJsonAtomic(join(paths.compatDir, 'compat.json'), {
+            redirect_to: artifactRootRelative,
+            manifest: relativeManifest,
+            error: error?.message ?? String(error)
+        });
+    }
+    const localCompatPath = join(paths.localCompatDir, 'manifest.json');
+    try {
+        await symlink(relative(paths.localCompatDir, paths.manifestPath), localCompatPath);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return;
+        }
+        await writeJsonAtomic(localCompatPath, {
+            redirect_to: artifactRootRelative,
+            manifest: relativeManifest
+        });
+    }
+}
+function buildCommandEntries(pipeline) {
+    return pipeline.stages.map((stage, index) => buildCommandEntry(stage, index + 1));
+}
+function buildCommandEntry(stage, index) {
+    if (stage.kind === 'command') {
+        return commandStageToManifest(stage, index);
+    }
+    return subPipelineStageToManifest(stage, index);
+}
+function commandStageToManifest(stage, index) {
+    return {
+        index,
+        id: stage.id,
+        title: stage.title,
+        command: stage.command,
+        kind: 'command',
+        status: 'pending',
+        started_at: null,
+        completed_at: null,
+        exit_code: null,
+        summary: null,
+        log_path: null,
+        error_file: null,
+        sub_run_id: null
+    };
+}
+function subPipelineStageToManifest(stage, index) {
+    return {
+        index,
+        id: stage.id,
+        title: stage.title,
+        command: null,
+        kind: 'subpipeline',
+        status: 'pending',
+        started_at: null,
+        completed_at: null,
+        exit_code: null,
+        summary: null,
+        log_path: null,
+        error_file: null,
+        sub_run_id: null
+    };
+}

package/dist/orchestrator/src/cli/run/manifestPersister.js

@@ -0,0 +1,88 @@
+import { saveManifest, writeHeartbeatFile } from './manifest.js';
+export class ManifestPersister {
+    manifest;
+    paths;
+    persistIntervalMs;
+    now;
+    writeManifest;
+    writeHeartbeat;
+    dirtyManifest = false;
+    dirtyHeartbeat = false;
+    timer = null;
+    timerResolver = null;
+    lastPersistAt = 0;
+    pendingPersist = Promise.resolve();
+    constructor(options) {
+        this.manifest = options.manifest;
+        this.paths = options.paths;
+        this.persistIntervalMs = options.persistIntervalMs;
+        this.now = options.now ?? Date.now;
+        this.writeManifest = options.writeManifest ?? saveManifest;
+        this.writeHeartbeat = options.writeHeartbeat ?? writeHeartbeatFile;
+    }
+    schedule(options = {}) {
+        const { manifest: includeManifest = false, heartbeat: includeHeartbeat = false, force = false } = options;
+        this.dirtyManifest = this.dirtyManifest || includeManifest;
+        this.dirtyHeartbeat = this.dirtyHeartbeat || includeHeartbeat;
+        if (!this.dirtyManifest && !this.dirtyHeartbeat) {
+            return this.pendingPersist;
+        }
+        if (force) {
+            this.clearTimer();
+            if (this.timerResolver) {
+                const resolver = this.timerResolver;
+                this.timerResolver = null;
+                resolver();
+                return this.pendingPersist;
+            }
+            this.pendingPersist = this.pendingPersist.then(() => this.flushPersist());
+            return this.pendingPersist;
+        }
+        if (this.timer) {
+            return this.pendingPersist;
+        }
+        const waitMs = Math.max(0, this.lastPersistAt + this.persistIntervalMs - this.now());
+        this.pendingPersist = this.pendingPersist
+            .then(() => new Promise((resolve) => {
+            this.timerResolver = resolve;
+            this.timer = setTimeout(() => {
+                this.clearTimer();
+                resolve();
+            }, waitMs);
+        }))
+            .then(() => this.flushPersist());
+        return this.pendingPersist;
+    }
+    flush() {
+        return this.schedule({ force: true });
+    }
+    clearTimer() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    async flushPersist() {
+        if (!this.dirtyManifest && !this.dirtyHeartbeat) {
+            return;
+        }
+        const writeManifest = this.dirtyManifest;
+        const writeHeartbeat = this.dirtyHeartbeat;
+        this.dirtyManifest = false;
+        this.dirtyHeartbeat = false;
+        this.lastPersistAt = this.now();
+        if (writeManifest) {
+            await this.writeManifest(this.paths, this.manifest);
+        }
+        if (writeHeartbeat) {
+            await this.writeHeartbeat(this.paths, this.manifest);
+        }
+    }
+}
+export async function persistManifest(paths, manifest, persister, options = {}) {
+    if (persister) {
+        await persister.schedule({ manifest: true, force: options.force });
+        return;
+    }
+    await saveManifest(paths, manifest);
+}

package/dist/orchestrator/src/cli/run/runPaths.js

@@ -0,0 +1,30 @@
+import { join, relative } from 'node:path';
+import { sanitizeRunId } from '../../persistence/sanitizeRunId.js';
+export function resolveRunPaths(env, runId) {
+    const safeRunId = sanitizeRunId(runId);
+    const runDir = join(env.runsRoot, env.taskId, 'cli', safeRunId);
+    const manifestPath = join(runDir, 'manifest.json');
+    const heartbeatPath = join(runDir, '.heartbeat');
+    const resumeTokenPath = join(runDir, '.resume-token');
+    const logPath = join(runDir, 'runner.ndjson');
+    const commandsDir = join(runDir, 'commands');
+    const errorsDir = join(runDir, 'errors');
+    const compatDir = join(env.runsRoot, env.taskId, 'mcp', safeRunId);
+    const compatManifestPath = join(compatDir, 'manifest.json');
+    const localCompatDir = join(env.runsRoot, 'local-mcp', safeRunId);
+    return {
+        runDir,
+        manifestPath,
+        heartbeatPath,
+        resumeTokenPath,
+        logPath,
+        commandsDir,
+        errorsDir,
+        compatDir,
+        compatManifestPath,
+        localCompatDir
+    };
+}
+export function relativeToRepo(env, targetPath) {
+    return relative(env.repoRoot, targetPath);
+}

package/dist/orchestrator/src/cli/selfCheck.js

@@ -0,0 +1,12 @@
+import process from 'node:process';
+import { loadPackageInfo } from './utils/packageInfo.js';
+export function buildSelfCheckResult() {
+    const pkg = loadPackageInfo();
+    return {
+        status: 'ok',
+        name: pkg.name ?? 'unknown',
+        version: pkg.version ?? 'unknown',
+        node: process.version,
+        timestamp: new Date().toISOString()
+    };
+}