/**
 * requireRuntime — null-guard helper for MCP tool handlers.
 *
 * When Synapse init silently fails, `hctx.nexusRef` is still assigned but its
 * internal engines are null.  Accessing any engine method then throws a raw
 * TypeError back to the caller instead of a structured envelope.
 *
 * Call this at the top of every handler that touches hctx.nexusRef:
 *
 *   const err = requireRuntime(hctx);
 *   if (err) return err;
 *
 * Returns a ready-to-return MCP content-block envelope when the runtime is
 * absent, or null when everything is healthy.
 */
export function requireRuntime(hctx) {
    if (!hctx.nexusRef) {
        const payload = JSON.stringify({
            status: 'error',
            code: 'runtime-cold',
            message: 'Nexus runtime not initialized',
            retriable: true,
            hint: 'The Nexus runtime failed to initialize. Check stderr for `synapse-init-failed reason=...` and re-run `nexus-prime daemon` after fixing the underlying issue.',
        }, null, 2);
        return { content: [{ type: 'text', text: payload }] };
    }
    return null;
}
